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Honorable Commissioner: 



This is an Appeal Brief filed pursuant to 37 CFR § 41.37 in response to the Final Office 
Action of June 30, 2005 ('Final Office Action'), and pursuant to the Notice of Appeal 
filed September 30, 2005. 



REAL PARTY IN INTEREST 



The real party in interest is the patent assignee, International Business Machines 
Corporation ("IBM"), a New York corporation having a place of business at Armonk, 
New York 10504. 
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RELATED APPEALS AND INTERFERENCES 

There are no related appeals or interferences. 

STATUS OF CLAIMS 

Claims 1-60 are pending in the case. All pending claims are on appeal. 

STATUS OF AMENDMENTS 

No amendments were submitted after final rejection. The claims as currently presented 
are included in the Appendix of Claims that accompanies this Appeal Brief 

SUMMARY OF CLAIMED SUBJECT MATTER 

Applicants provide the following concise summary of the claimed subject matter 
according to 37 CFR§ 41.37(c)(l)(v), including references to specification by page and 
line number and to the drawing(s) if any, by reference characters. 

In summary, this specification discloses broadcasting user controls for streaming digital 
content from a multiplicity of sources of digital information to a multiplicity of client 
devices (described for example at lines 10-16 on page 12 and at references 102, 105, 106 
in Figure 1), embodiments implemented in conjunction with a network of digital 
computers (described for example at lines 10-16 on page 12 and at reference 108 in 
Figure 1), at least one of the digital computers comprising a content server (described for 
example at lines 10-16 on page 12 and at reference 100 in Figure 1) upon which 
embodiments are implemented in computer memory and upon at least one computer 
processor, embodiments typically including receiving from a remote director a director 
instruction, the director instruction comprising an identification of a selected user control 
(described for example at line 26 on page 12 through line 3 on page 13 and at references 
104, 202, 204 in Figure 2); extracting, in dependence upon the director instruction, from a 
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store of user controls, the identified selected user control (described for example at lines 
8-12 on page 24 and at references 610, 61 1, and 614 in Figure 5); identifying, in 
dependence upon the director instruction, a data communications program that 
administers data communications between the content server and a client device 
(described for example at lines 14-20 on page 24 and at references 100, 102, 204, and 
406 in Figure 5); encoding through the data communications program, in dependence 
upon the selected user control, a new HTML document (described for example at lines 
14-20 on page 24 and at references 406, 614, 622, and 624 in Figure 5); and 
downloading, through the identified data communications program, the new HTML 
document to the client device (described for example at lines 14-20 on page 24 and at 
references 102, 406, 624, and 626 in Figure 5). 

All such references to the specification identify descriptions and discussions that are part 
of the detailed descriptions of exemplary embodiments of the present invention in the 
present application. Such descriptions and discussions are not limitations of the claims in 
the present application. The only limitations of the claims are set forth in the claims 
themselves. 

GROUNDS OF REJECTION 

Claims 1-60 of the present application are rejected in the Final Office Action dated June 
30, 2005, for obviousness-type double patenting over claims 1-22 of copending 
Application No. 09/882174, overclaims 10-15 of copending Application No. 09/881919, 
over claims 1-20 of copending Application No. 09/881915, and over claims 1-12 of 
copending Application No. 09/882173. As explained in detail below, Applicants 
respectfully traverse the obviousness-type double patenting rejections of the present 
claims. 

Independent claims 1,21, and 41 stand rejected under 35 U.S.C § 103(a) as unpatentable 
over a first reference entitled A pplication Server Solution Guide, Enterprise Edition: 
Getting Started , Nusbaum, et al., May 2000, pages 1-45, 416-434 (hereafter 'Nusbaum'), 
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and in view of a second reference entitled Java Media Framework API Guide , JMP 2.0 
FCS, November 19, 1999, Sun Microsystems, pages 1-66, 109-135, 173-178 (hereafter 
'Sun'). As explained in detail below, applicants respectfully traverse the rejections of the 
present claims under 35 USC § 103(a). 

ARGUMENT 

REJECTIONS FOR CLAIMS 1-60 BASED ON OBVIOUSNESS-TYPE 
DOUBLE PATENTING ARE IMPROPER 

All claims in the present application are rejected in the Final Office Action for 
obviousness-type double patenting over claims 1-22 of copending Application No. 
09/882174, overclaims 10-15 of copending Application No. 09/881919, over claims 1-20 
of copending Application No. 09/881915, and over claims 1-12 of copending Application 
No. 09/882173. 

The law governing double patenting is that the analysis employed in an obviousness-type 
double patenting determination parallels the guidelines for a 35 U.S.C. § 103(a) rejection. 
The factual inquiries set forth in Graham v. John Deere Co., 383 U.S. 1, 148 USPQ 459 
(1966) are applied for establishing a background for determining obviousness under 35 
U.S.C. § 103 and are employed when making an obviousness-type double patenting 
rejection. Manual of Patent Examining Procedure § 804 IIB1. The Graham factual 
inquiries require the Examiner to: 

• determine the scope and content of the art as described in each co-pending 
application; 

• determine the differences between the scope and content of the art as described in 
each co-pending application and the claims at issue; 

• determine the level of ordinary skill in the pertinent art; and 
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o evaluate any objective indicia of nonobviousness. 

Co-pending Application No. 09/882174 

The Final Office Action rejects claims 1-60 for obviousness-type double patenting as 
being unpatentable over 1-22 of co-pending Application No. 09/882174. The Final 
Office Action at page 8 states: 

. . . they are not patentably distinct from each other because the limitations 
of the independent claims 1,21,41 are similar to claim 1 of copending 
Application No. 09/882174. The limitations "remote direction of 
streaming digital content from a content server to a client devices using 
remote director" is equivalent to the use of content information, 
transcoding gateway for providing director instructions to stream digital 
content, and the use of email containing digital content. The limitations of 
dependent claims 2-20, 22-40, 42-60, are similar to claims 2-22 of 
copending Application No. 09/882174. 

As described above, the Final Office Action must apply the Graham factors to establish 
the required background for a double patenting rejection. Although the Final Office 
Action does not even mention the Graham factors, the Final Office Action at page 8 
states: 

The co-pending application handles transcoding information using the 
network device. The current application also handles transcoding 
information using the network device. The claimed subject matter of the 
co-pending application does not mention about the broadcasting of user 
controls for streaming. However, broadcasting of user controls for 
streaming is well known in the art, for example, paragraph 4 of the 
Background of the invention section of the specification discloses it. The 
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broadcasting related information would help for transcoding by the 
software. 

Applicants take the assertion in the Final Office Action that co-pending Application No. 
09/882174 "handles transcoding information using the network device" as a 
determination under Graham of the scope and content of the art as described in co- 
pending application No. 09/882174. In response, Applicants note that the Final Office 
Action mischaracterizes co-pending application No. 09/882174 by asserting that the co- 
pending application transcodes information using a network device. Co-pending 
application No. 09/8821 74 claims a transcoding gateway for "transcoding the digital 
object into a digital file having a digital format and a file name. . . ." The scope and 
content of the art as described in co-pending application No. 09/882174 therefore 
includes a transcoding gateway that transcodes a digital object into a digital file having a 
digital format and a file name. The scope and content of the art as described in co- 
pending application No. 09/882174 does not include any network device that transcodes 
information as asserted in the Final Office Action. Because the Final Office Action does 
not properly determine the scope and content of the art as described in co-pending 
application No. 09/882174, the Final Office Action does not establish the necessary 
background for determining obviousness. Without establishing the necessary background 
for determining obviousness, the Final Office Action cannot support an obviousness-type 
double patenting rejection, and the rejections of claims 1-60 should be withdrawn. 

Applicants take the assertion in the Final Office Action that "[t]he current application 
also handles transcoding information using the network device" and that "[t]he claimed 
subject matter of the co-pending application does not mention about the broadcasting of 
user controls for streaming" as a determination under Graham of the differences between 
the scope and content of the art as described in co-pending application No. 09/882174 
and the claims at issue. In response, Applicants note that the Final Office Action 
mischaracterizes the present application by asserting that the present application 
transcodes information using a network device. Independent claim 1 of the present 
application claims: 
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1 . A method of broadcasting user controls for streaming digital 

content from a multiplicity of sources of digital information to a 
multiplicity of client devices, the method implemented in 
conjunction with a network of digital computers, at least one of the 
digital computers comprising a content server upon which the steps 
of the method are implemented in computer memory and upon at 
least one computer processor, the method comprising the steps of: 

receiving from a remote director a director instruction, the director 
instruction comprising an identification of a selected user control; 

extracting, in dependence upon the director instruction, from a 
store of user controls, the identified selected user control; 

identifying, in dependence upon the director instruction, a data 
communications program that administers data communications 
between the content server and a client device; 

encoding through the data communications program, in 
dependence upon the selected user control, a new HTML 
document; and 

downloading, through the identified data communications 
program, the new HTML document to the client device. 

Claim 1 of the present application does not mention "transcoding information using the 
network device." In fact, claim 1 of the present application does not mention 
"transcoding" at all. The scope and content of the art as described in the present 
application is not "transcoding information using the network device" as asserted in the 
Final Office Action. Because the Final Office Action does not properly determine the 
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scope and content of the art as described in the present application, the Final Office 
Action cannot determine the differences between the scope and content of the art as 
described in co-pending application No. 09/882174 and the claims at issue. The Final 
Office Action therefore does not establish the necessary background for determining 
obviousness. Without establishing the necessary background for determining 
obviousness, the Final Office Action cannot support an obviousness-type double 
patenting rejection, and the rejections of claims 1-60 should be withdrawn. 

Applicants further assume that the Final Office Action at page 8 attempts to determine 
under Graham the level of ordinary skill in the pertinent art by stating: 

However, broadcasting of user controls for streaming is well known in the 
art, for example, paragraph 4 of the Background of the invention section 
of the specification discloses it. The broadcasting related information 
would help for transcoding by the software. 

In response, Applicants' respectfully note that the section of Applicants specification 
entitled 'Background of the Invention' does not contain a fourth paragraph. The section 
of Applicants specification entitled 'Background of the Invention' therefore cannot 
disclose at paragraph 4 "broadcasting of user controls for streaming. . ." as asserted in the 
Final Office Action. Because the Final Office Action has not demonstrated the level of 
ordinary skill in the pertinent art includes "broadcasting of user controls for streaming," 
the Final Office Action does not establish the necessary background for determining 
obviousness. Without establishing the necessary background for determining 
obviousness, the Final Office Action cannot support an obviousness-type double 
patenting rejection, and the rejections of claims 1-60 should be withdrawn. 

Furthermore, even if the section of Applicants specification entitled 'Background of the 
Invention' disclosed "broadcasting of user controls for streaming" as asserted in the Final 
Office Action, which it does not, Applicants' claims would not be obvious to a person of 
ordinary skill in the art knowledgeable of "broadcasting of user controls for 
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streaming. ..." Applicants claim a method for "broadcasting user controls for streaming 
digital content from a multiplicity of sources of digital information to a multiplicity of 
client devices. . that includes the elements and limitations described above. 
"[B]roadcasting of user controls for streaming" is not broadcasting user controls for 
streaming digital content from a multiplicity of sources of digital information to a 
multiplicity of client devices as claimed in the present application. Applicants' claims 
therefore would not be obvious to a person of ordinary skill in the art knowledgeable of 
"broadcasting of user controls for streaming. ..." The Final Office Action does not 
establish the necessary background for determining obviousness. Without establishing 
the necessary background for determining obviousness, the Final Office Action cannot 
support an obviousness-type double patenting rejection, and the rejections of claims 1-60 
should be withdrawn. 

Co-Pending Application No. 09/881919 

The Final Office Action rejects claims 1-60 for obviousness-type double patenting as 
being unpatentable over claims 10-15 of co-pending Application No. 09/881919. The 
Final Office Action at page 9 states: 

. . . they are not patentably distinct from each other because the limitations of the 
independent claims 1,21,41 are similar to claim 10 of co-pending Application 
No. 09/881919. The limitations, "remote direction of streaming digital content 
from a content server to a client devices using remote director" is equivalent to 
the use of a content server through which digital content is transcoded into 
streams of multimedia data, the streams communicated via network to client 
devices, use of the digital content for streaming, use of remote director 
instructions comprising hyperlinked URSs invoked through a network-capable 
device. The limitations of dependent claims 2-20, 22-40, 42-60, are similar to 
claims 11-15 of co-pending Application No. 09/881919. 
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As described above, the Final Office Action must apply the Graham factors to establish 
the required background for a double patenting rejection. Although the Final Office 
Action does not even mention the Graham factors, the Final Office Action does recite the 
same assertions made regarding co-pending Application No. 09/882174 above by stating; 

The co-pending application handles transcoding information using the 
network device. The current application also handles transcoding 
information using the network device. The claimed subject matter of the 
co-pending application does not mention about the broadcasting of user 
controls for streaming. However, broadcasting of user controls for 
streaming is well known in the art, for example, paragraph 4 of the 
Background of the invention section of the specification discloses it. The 
broadcasting related information would help for transcoding by the 
software. 

Applicants take such assertions as an attempt to apply the Graham factors regarding this 
co-pending Application No. 09/881919. In response, Applicants note that the Final 
Office Action does not establish the necessary background for determining obviousness 
for the reasons discussed above with regard to co-pending Application No. 09/882174. 
The Final Office Action therefore cannot support an obviousness-type double patenting 
rejection, and the rejections of claims 1-60 should be withdrawn. 

Co-Pending Application No. 09/881915 

The Final Office Action rejects claims 1-60 for obviousness- type double patenting as 
being unpatentable over claims 1-20 of co-pending Application No. 09/881915. The 
Final Office Action at page 10 states: 

. . . they are not patentably distinct from each other because the limitations of the 
independent claims 1,21,41 are similar to claim 1 of co-pending Application No. 
09/881915. The limitations, "remote direction of streaming digital content from a 
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content server to a client devices using remote director" is equivalent to the use of 
streaming digital content from a multiplicity of sources of digital information to a 
multiplicity of client devices, use of network of digital computers comprising a 
content server. The limitations of dependent claims 2-20, 22-40, 42-60, are 
similar to claims 2-12 of co-pending Application No. 09/881915. 

As described above, the Final Office Action must apply the Graham factors to establish 
the required background for a double patenting rejection. Although the Final Office 
Action does not even mention the Graham factors, the Final Office Action does recite the 
same assertions made regarding co-pending Application No. 09/882174 above by stating: 

The co-pending application handles transcoding information using the 
network device. The current application also handles transcoding 
information using the network device. The claimed subject matter of the 
co-pending application does not mention about the broadcasting of user 
controls for streaming. However, broadcasting of user controls for 
streaming is well known in the art, for example, paragraph 4 of the 
Background of the invention section of the specification discloses it. The 
broadcasting related information would help for transcoding by the 
software. 

Applicants take such assertions as an attempt to apply the Graham factors regarding this 
co-pending Application No. 09/881915. In response, Applicants note that the Final 
Office Action does not establish the necessary background for determining obviousness 
for the reasons discussed above with regard to co-pending Application No. 09/8821 74. 
The Final Office Action therefore cannot support an obviousness-type double patenting 
rejection, and the rejections of claims 1-60 should be withdrawn. 
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Co-Pending Application No. 09/882173 

The Final Office Action rejects claims 1-60 for obviousness-type double patenting as 
being unpatentable over claims 1-12 of co-pending Application No. 09/882173. The 
Final Office Action at page 1 1 states: 

. . . they are not patentably distinct from each other because the limitations of the 
independent claims 1, 21, 41 are similar to claim 1 of co-pending Application No. 
09/882173. The limitations, "remote direction of streaming digital content from a 
content server to a client devices using remote director" is equivalent to the use of 
remote direction of streaming digital content from a multiplicity of sources of 
digital information to a multiplicity of client devices upon a network of digital 
computer comprising a content server receiving digital content from the sources 
and the digital content having a multiplicity of digital formats. The limitations of 
dependent claims 2-20, 22-40, 42-60, are similar to claims 2-11 of co-pending 
Application No. 09/882173. 

As described above, the Final Office Action must apply the Graham factors to establish 
the required background for a double patenting rejection. Although the Final Office 
Action does not even mention the Graham factors, the Final Office Action does recite the 
same assertions made regarding co-pending Application No. 09/882174 above by stating: 

The co-pending application handles transcoding information using the 
network device. The current application also handles transcoding 
information using the network device. The claimed subject matter of the 
co-pending application does not mention about the broadcasting of user 
controls for streaming. However, broadcasting of user controls for 
streaming is well known in the art, for example, paragraph 4 of the 
Background of the invention section of the specification discloses it. The 
broadcasting related information would help for transcoding by the 
software. 
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Applicants take such assertions as an attempt to apply the Graham factors regarding this 
co-pending Application No. 09/882173. In response, Applicants note that the Final 
Office Action does not establish the necessary background for determining obviousness 
for the reasons discussed above with regard to co-pending Application No. 09/882174. 
The Final Office Action therefore cannot support an obviousness-type double patenting 
rejection, and the rejections of claims 1-60 should be withdrawn. 

Conclusion 

The Final Office Action does not establish the necessary background for determining 
obviousness required by an obviousness-type double patenting rejection of claims 1-60 in 
the present application over claims 1-22 of co-pending Application No. 09/882174, over 
claims 10-15 of co-pending Application No. 09/881919, over claims 1-20 of co-pending 
Application No. 09/881915, and over claims 1-12 of co-pending Application No. 
09/8821 73. Based on the reasoning provided in the Final Office Action, no person of 
ordinary skill in the art would conclude that claims 1-60 in the present case are obvious in 
view of claims 1-22 of co-pending Application No. 09/882174, over claims 10-15 of co- 
pending Application No. 09/88 1 91 9, over claims 1 -20 of co-pending Application No. 
09/881915, and over claims 1-12 of co-pending Application No. 09/882173. Applicants 
therefore respectfully traverse the rejections of claims 1-60 and request reconsideration of 
claims 1-60 in light of the present remarks. 

REJECTIONS FOR CLAIMS 1-60 BASED ON OBVIOUSNESS 
UNDER 35 U.S.C § 103(a) ARE IMPROPER 

Claims 1-60 are in the case. Independent claims 1,21, and 41 stand rejected for 
obviousness under 35 U.S.C § 103(a) as unpatentable over a first reference entitled 
Application Server Solution Guide, Enterprise Edition: Getting Started , Nusbaum, et al., 
May 2000, pages 1-45, 416-434 (hereafter 'Nusbaum'), and in view of a second reference 
entitled Java Media Framework API Guide , JMP 2.0 FCS, November 19, 1999, Sun 
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Microsystems, pages 1-66, 109-135, 173-178 (hereafter 'Sun'). To establish a prima 
facie case of obviousness, three basic criteria must be met. Manual of Patent Examining 
Procedure §2142. The first element of a prima facie case of obviousness under 35 
U.S.C. § 103 is that Nusbaum and Sun must teach or suggest all of Applicants' claim 
limitations. In re Royka, 490 F.2d 981, 985, 180 USPQ 580, 583 (CCPA 1974). The 
second element of a prima facie case of obviousness under 35 U.S.C. § 103 is that there 
must be a suggestion or motivation to combine Nusbaum and Sun. In re Vaeck, 947 F.2d 
488, 493, 20 USPQ2d 1438, 1442 (Fed. Cir. 1991). The third element of a prima facie 
case of obviousness under 35 U.S.C. § 103 is that there must be a reasonable expectation 
of success in the proposed combination of Nusbaum and Sun. In re Merck & Co., Inc., 
800 F.2d 1091, 1097, 231 USPQ 375, 379 (Fed. Cir. 1986). As demonstrated below, the 
combination of Nusbaum and Sun does not establish a prima facie case of obviousness. 
The rejection of independent claims 1,21, and 41 should therefore be withdrawn and the 
case should be allowed. 

Nusbaum and Sun Do Not Teach 
Each and Every Element of the Independent Claims 

To establish a prima facie case of obviousness, the proposed combination of Nusbaum 
and Sun must disclose all of applicants' claim limitations. In re Royka, 490F.2d 981, 
985, 180 USPQ 580, 583 (CCPA 1974). Independent claim 1 of the present application 
claims: 

1 . A method of broadcasting user controls for streaming digital 

content from a multiplicity of sources of digital information to a 
multiplicity of client devices, the method implemented in 
conjunction with a network of digital computers, at least one of the 
digital computers comprising a content server upon which the steps 
of the method are implemented in computer memory and upon at 
least one computer processor, the method comprising the steps of: 
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receiving from a remote director a director instruction, the director 
instruction comprising an identification of a selected user control; 

extracting, in dependence upon the director instruction, from a 
store of user controls, the identified selected user control; 

identifying, in dependence upon the director instruction, a data 
communications program that administers data communications 
between the content server and a client device; 

encoding through the data communications program, in 
dependence upon the selected user control, a new HTML 
document; and 

downloading, through the identified data communications 
program, the new HTML document to the client device. 

Independent claims 21 and 41 are respective system and computer program product 
claims that correspond to the method of independent claim 1 . In rejecting claims 1,21, 
and 41, the Final Office Action at page 12 states that Nusbaum teaches "broadcasting 
objects from a multiplicity of sources of digital information to a multiplicity of client 
devices (e.g., section 1.3.2. page 12)...." Applicants take this statement from the Final 
Office Action as an assertion that section 1.3.2 of Nusbaum teaches "broadcasting user 
controls for streaming digital content from a multiplicity of sources of digital information 
to a multiplicity of client devices" as claimed in the present application. What section 
1.3.2 of Nusbaum actually teaches is an "EJB architecture in brief where 'EJB' stands 
for Enterprise JavaBeans™. An Enterprise JavaBeans™ is a server-side object that 
conforms to the Enterprise JavaBeans™ Specification. The EJB specification describes 
the server-side component architecture of the Java 2 Enterprise Edition ('J2EE') platform 
that provides a framework for components to "plug in" to a server and extend that 
server's functionality. A server-side object that conforms to the Enterprise JavaBeans™ 
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Specification is not broadcasting user controls for streaming digital content from a 
multiplicity of sources of digital information to a multiplicity of client devices as claimed 
in the present application. The section of Nusbaum entitled 'EJB architecture in brief 
therefore does not teach broadcasting user controls for streaming digital content from a 
multiplicity of sources of digital information to a multiplicity of client devices as claimed 
in the present application. The Final Office Action does not produce references that 
teach each and every element of independent claims 1, 21, and 41, and the rejections 
should be withdrawn. 

In rejecting claims 1,21, and 41, the Final Office Action at page 12 states that Nusbaum 
teaches "a content server (e.g., server containing web content, page 13)...." What page 
13 actually teaches is an "EJB environment and interaction with other components," the 
other components including a web server. An Enterprise JavaBeans™ environment that 
includes a web server is not a content server as claimed in the present application. The 
web server of Nusbaum therefore does not teach a content server as claimed in the 
present application. The Final Office Action does not produce references that teach each 
and every element of independent claims 1,21, and 41, and the rejections should be 
withdrawn. 

In rejecting claims 1,21, and 4 1 , the Final Office Action at page 1 2 states that Nusbaum 
teaches "receiving from a remote director a director instruction, the director instruction 
comprising an identification of a selected object (e.g., page 4 and section 2.1.1.1, pages 
3 1 and 32). ..." Applicants take this statement from the Final Office Action as an 
assertion that page 4 of Nusbaum and section 2.1.1.1 of Nusbaum teach "receiving from a 
remote director a director instruction, the director instruction comprising an identification 
of a selected user control" as claimed in the present application. What page 4 of 
Nusbaum actually teaches is an overview of version 2.1 of the "Java Servlet API" and the 
"IBM extensions to the Servlet API V2.1," where 'APT stands for Application 
Programming Interface. Section 2.1.1.1 of Nusbaum actually teaches an EJB server 
architecture that includes an "EJB server runtime," "EJB containers," and "Enterprise 
Java beans" that together provide services such as a "deployment tool," "naming 
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services," and "security services." Nusbaum's EJB server architecture has nothing 
whatsoever to do with receiving from a remote director a director instruction, the director 
instruction comprising an identification of a selected user control as claimed in the 
present application. In fact, page 4 of Nusbaum and section 2. 1 .1 .1 of Nusbaum never 
once mentions "receiving," "remote director," "director instruction," or "user control." 
Nusbaum's EJB server architecture therefore does not teach the elements and limitations 
of the claims of the present application as cited in the Final Office Action. Because the 
Final Office Action does not produce references that teach each and every element of the 
independent claims 1, 21, and 41, the rejections should be withdrawn. 

In rejecting claims 1,21, and 41, the Final Office Action at page 13 states that Nusbaum 
teaches "extracting, in dependence upon the director instruction, from a store of objects, 
the identified selected object (e.g., section 1.2, page 2, section 8.1.10.1, page 420)...." 
Applicants take this statement from the Final Office Action as an assertion that sections 
1.2 and 8.1.10.1 of Nusbaum teach "extracting, in dependence upon the director 
instruction, from a store of user controls, the identified selected user control.. ." as 
claimed in the present application. What section 1.2 of Nusbaum actually teaches is a 
general description of JavaServlet™ that includes "servlet lifecycles," a "Java Servlet 
API V2.1 Overview," the "IBM extensions to the Servlet API V2.1," "Servlet API V2.1 
details," and "Changes to package supported in WAS V.2," where 'WAS' stands for 
WebSphere Application Server. Section 8. 1 . 1 0. 1 of Nusbaum teaches an "LDIF format" 
where 4 LDIF' stands for Lightweight directory access protocol Data Interchange Format. 
LDIF is a format for representing LDAP entries in text form. Nusbaum's general 
description of JavaServlet™ and the LDIF of Nusbaum has nothing whatsoever to do 
with extracting, in dependence upon the director instruction, from a store of user controls, 
the identified selected user control as claimed in the present application. In fact, sections 
1.2 and 8.1.10.1 of Nusbaum never even once mentions "director instruction" or "user 
control." Nusbaum's general description of JavaServlet™ and the LDIF of Nusbaum 
therefore do not teach extracting, in dependence upon the director instruction, from a 
store of user controls, the identified selected user control as claimed in the present 
application. Because the Final Office Action does not produce references that teach each 
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and every element of the independent claims 1, 21, and 41, the rejections should be 
withdrawn. 

In rejecting claims 1,21, and 41, the Final Office Action at page 13 states that Nusbaum 
teaches: 

identifying, in dependence upon the director instruction, a data 
communications program that administers data communications between 
the content server and a client device (e.g., section 7.4, page 375, servlet 
to be used specified by the servlet aliases, page 2, sections 1.1 and 1.2, 
pages 1 and 2). 

Applicants take this statement from the Final Office Action as an assertion that Nusbaum 
at sections 1.2, and 7.4 teach "identifying, in dependence upon the director instruction, a 
data communications program that administers data communications between the content 
server and a client device. . as claimed in the present application. What section 1 . 1 of 
Nusbaum actually discloses is a general use of the term 'application' in the context of 
IBM's WebSphere® product that provides integration and application infrastructure. 
What section 1.2 of Nusbaum actually teaches is a general description of JavaServlet™ 
that includes "servlet lifecycles," a "Java Servlet API V2.1 Overview," the "IBM 
extensions to the Servlet API V2.1," "Servlet API V2.1 details," and "Changes to 
package supported in WAS V.2," where 'WAS' stands for WebSphere Application 
Server. Applicants cannot comment on section 7.4 of Nusbaum because section 7.4 was 
not provided to Applicants with the Office Action. Nusbaum 's general use of the term 
'application' in the context of IBM's WebSphere® product and general description of 
JavaServlet™ is not identifying, in dependence upon the director instruction, a data 
communications program that administers data communications between the content 
server and a client device as claimed in the present application. Nusbaum's general use 
of the term 'application' in the context of IBM's WebSphere® product and general 
description of JavaServlet™ therefore does not teach identifying, in dependence upon the 
director instruction, a data communications program that administers data 
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communications between the content server and a client device as claimed in the present 
application. Because the Final Office Action does not produce references that teach each 
and every element of the independent claims 1,21, and 41, the rejections should be 
withdrawn. 

In rejecting claims 1,21, and 41, the Final Office Action at page 13 states that Nusbaum 
teaches: 

encoding through the data communications program, in dependence upon 
the selected object (e.g., use of Enterprise Java Beans to encode, section 
2.1.1.1, pages 31 and 32), a new HTML document (e.g., creation of 
HTML document using of servlets, pages 13 and 36). . .. 

Applicants take this statement from the Final Office Action as an assertion that Nusbaum 
at section 2.1.1.1 and pages 13 and 36 teach "encoding through the data communications 
program, in dependence upon the selected user control, a new HTML document. . as 
claimed in the present application. What section 2.1.1.1 of Nusbaum actually teaches is 
an EJB server architecture that includes an "EJB server runtime," "EJB containers," and 
"Enterprise Java beans" that together provide services such as a "deployment tool," 
"naming services," and "security services." Page 13 of Nusbaum teaches that "JSPs 
dynamically generate HTML. . .," where JSP stands for Java Server Pages. Page 36 of 
Nusbaum teaches a "WebSphere Application Server Standard Edition 3.0 runtime 
architecture" and an introduction to the "WebSphere Application Server Advanced 
Edition." Nusbaum at section 2.1.1.1 and pages 13 and 36 has nothing whatsoever to do 
with encoding through the data communications program, in dependence upon the 
selected user control, a new HTML document as claimed in the present application. In 
fact, Nusbaum at section 2.1.1.1 and pages 1 3 and 36 never even once mentions 
"encoding" or "user control." Nusbaum's EJB server architecture, characterization of 
JSPs, and descriptions relating to IBM's WebSphere® therefore does not teach encoding 
through the data communications program, in dependence upon the selected user control, 
a new HTML document as claimed in the present application. Because the Final Office 
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Action does not produce references that teach each and every element of the independent 
claims 1,21, and 41, the rejections should be withdrawn. 

In rejecting claims 1,21, and 41, the Final Office Action at page 13 states that Nusbaum 
teaches: 

downloading, through the identified data communications program, the 
new HTML document to the client device (e.g., use of servlets to 
download HTML documents for network servers and clients, section 1 .2, 
page 1, section 7.4, page 375, use of HTML section 1.2, page 2, section 
8.1.10.1, page 420. 

Applicants take this statement from the Final Office Action as an assertion that Nusbaum 
at sections 1.2, 7.4, 8.1.10.1 teach "downloading, through the identified data 
communications program, the new HTML document to the client device" as claimed in 
the present application. What section 1.2 of Nusbaum actually teaches is a general 
description of JavaServlet™ that includes "servlet lifecycles," a "Java Servlet API V2.1 
Overview," the "IBM extensions to the Servlet API V2.1," "Servlet API V2.1 details," 
and "Changes to package supported in WAS V.2," where 'WAS' stands for WebSphere 
Application Server. Section 8.1.10.1 of Nusbaum teaches an "LDIF format" where 
'LDIF' stands for Lightweight directory access protocol Data Interchange Format. LDIF 
is a format for representing LDAP entries in text form. Applicants cannot comment on 
section 7.4 of Nusbaum because section 7.4 was not provided to Applicants with the 
Office Action. Nusbaum' s general description of JavaServlet™ and the LDIF of 
Nusbaum is not downloading, through the identified data communications program, the 
new HTML document to the client device as claimed in the present application. 
Nusbaum' s general description of JavaServlet™ and the LDIF of Nusbaum therefore 
does not teach downloading, through the identified data communications program, the 
new HTML document to the client device as claimed in the present application. Because 
the Final Office Action does not produce references that teach each and every element of 
the independent claims 1,21, and 41, the rejections should be withdrawn. 
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In rejecting claims 1,21, and 41, the Final Office Action at page 13 states that Sun 
teaches "streaming digital content (e.g., streaming media, page 4, MPEG, JPEG, etc., 
video formatted content, page 6, transcoding the video contents, page 33). ..." What page 
4 of Sun actually teaches is definitions to some common terms used in streaming media 
including 'content type,' 'media stream,' 'multiplex,' 'track,' and so on. Page 6 of Sun 
merely discloses a chart of common video and audio formats. What page 33 of Sun 
actually teaches is a definition of transcoding as a "process of converting each track of 
media data from one input format to another." Sun's definition of transcoding and of 
some common streaming media terms along with Sun's chart of common video and audio 
formats does not teach streaming digital content as claimed in the present application. 
Because the Final Office Action does not produce references that teach each and every 
element of the independent claims 1,21, and 41, the rejections should be withdrawn. 

In rejecting claims 1,21, and 41, the Final Office Action at page 13 states that Sun 
teaches "to broadcast user controls (e.g., JMF Applet containing media controls, 
Appendix A, page 1 73). . . ." What Appendix A of Sun actually teaches is a Java Applet 
that creates a "simple media player with a media event listener." Sun's simple media 
player with a media event listener is not broadcasting user controls for streaming digital 
content from a multiplicity of sources of digital information to a multiplicity of client 
devices as claimed in the present application. In fact, Appendix A never once mentions 
"broadcasting user controls." Sun's simple media player with a media event listener does 
not teach broadcasting user controls for streaming digital content from a multiplicity of 
sources of digital information to a multiplicity of client devices as claimed in the present 
application. Because the Final Office Action does not produce references that teach each 
and every element of the independent claims 1,21, and 41, the rejections should be 
withdrawn. 

In rejecting claims 1,21, and 41, the Final Office Action at page 13 states that Sun 
teaches "that object being used for receiving and extraction steps is user control (e.g., 
Handling of containing media controls of JMF Applet, Appendix A, page 173). 

21 



AUS920010582US1 
APPEAL BRIEF 

Applicants take this statement from the Final Office Action as an assertion that Sun at 
Appendix A teaches "user controls" in the elements of Applicants' claims for "receiving 
from a remote director a director instruction, the director instruction comprising an 
identification of a selected user control" and "extracting, in dependence upon the director 
instruction, from a store of user controls, the identified selected user control." As 
mentioned above, Appendix A of Sun actually teaches a Java Applet that creates a 
"simple media player with a media event listener." Sun's simple media player with a 
media event listener does not include a selected user control identifier or an identified 
selected user control extracted from a store of user controls as claimed in the present 
application. In fact, Sun does not even mention "an identification of a selected user 
control" or an "identified selected user control." Sun's simple media player with a media 
event listener does not teach user controls as claimed in the present application. Because 
the Final Office Action does not produce references that teach each and every element of 
the independent claims 1,21, and 41, the rejections should be withdrawn. 

The Cited References Set Forth No Suggestion to 
Modify or Combine Nusbaum and Sun 

To establish a prima facie case of obviousness, there must be a suggestion or motivation 
to modify or combine Nusbaum and Sun. In re Vaeck, 947 F.2d 488, 493, 20 USPQ2d 
1438, 1442 (Fed. Cir. 1991). "The mere fact that references can be combined or 
modified does not render the resultant combination obvious unless the prior art also 
suggests the desirability of the combination." In re Mills, 916 F.2d 680, 16 USPQ2d 
1430 (Fed. Cir. 1990). The Examiner has not pointed to any disclosure in Nusbaum or 
Sun suggesting the desirability of the combination. Moreover, there is no possibility 
whatsoever that the Examiner could ever point to any disclosure in Nusbaum or Sun 
suggesting the desirability of the combination. Nusbaum in fact makes no mention 
whatsoever of broadcast user controls, remote directors, or director instructions and 
therefore could not possibly suggest the desirability of the combination. In addition, no 
such suggestion occurs in Sun. Absent such a showing of desirability, the Examiner has 
impermissibly used "hindsight" occasioned by applicants' own teaching to reject the 
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claims. In re Surko, 1 1 F.3d 887, 42 U.S.P.Q.2d 1476 (Fed. Cir. 1997); In re VaecK 947 
F.2d 488m 20 U.S.P.Q.2d 1438 (Fed. Cir. 1991); In re Gorman, 933 F.2d 982, 986 5 18 
U.S.P.Q.2d 1885, 1888 (Fed. Cir. 1991); In re Bond 910 F.2d 831, 15 U.S.P.Q.2d 1566 
(Fed. Cir. 1990); In re Laskowski, 871 F,.2d 1 15, 1 17, 10 U.S.P.Q.2d 1397, 1398 (Fed. 
Cir. 1989). The proposed combination of Nusbaum and Sun therefore cannot possibly 
establish a prima facie case of obviousness. The rejections should be withdrawn, and the 
case should be allowed. 

There is No Reasonable Expectation Of Success in the 
Proposed Combination of Nusbaum and Sun 

To establish a prima facie case of obviousness, there must be a reasonable expectation of 
success in the proposed combination of Nusbaum and Sun. In re Merck & Co., Inc., 800 
F.2d 1091, 1097, 231 USPQ 375, 379 (Fed. Cir. 1986). The Examiner has not pointed to 
any disclosure in Nusbaum or Sun suggesting any expectation of success in such a 
combination. In fact, there can be no reasonable expectation of success in the proposed 
combination of Nusbaum and Sun because Nusbaum and Sun cannot be combined to 
provide broadcasting user controls for streaming digital content from a multiplicity of 
sources of digital information to a multiplicity of client devices as claimed in the present 
application. The Final Office Action bases this rejection on portions of Nusbaum that 
includes page 4, page 13, page 36, section 1.2, section 1.3.2, section 2.1.1.1, and section 
8. 1 . 10. 1 . As explained above, these references to Nusbaum teach an EJB execution 
environment and a kind of dynamic web page technology known as Java Server Pages or 
C JSP.' The Final Office Action also bases this rejection on portions of Sun that includes 
page 4, page 6, and page 33, which as explained above, merely provide some definitions 
regarding streaming media as the terms are used in the Java Media Framework. As 
described in Nusbaum, dynamic web page technology is methods and systems for 
building server pages on the fly. Dynamic web pages generally, and JSPs in particular, is 
not streaming media and does not combine with streaming media to provide broadcasting 
user controls for streaming digital content from a multiplicity of sources of digital 
information to a multiplicity of client devices as claimed in the present application. The 
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proposed combination of Nusbaum and Sun therefore cannot support a prima facie case 
of obviousness. The rejection should be withdrawn, and the case should be allowed. 

Nusbaum Teaches Away From the 
Claims of the Present Application 

Turning now to the substance of Nusbaum, Nusbaum actually teaches away from the 
current application. Teaching away from the claims is a per se demonstration of lack of 
prima facie obviousness. In re Dow Chemical Co., 837 F.2d 469, 5 U.S.P.Q.2d 1529 
(Fed. Cir. 1988); In re Fine, 837 F.2d 1071, 5 U.S.P.Q.2d 1596 (Fed. Cir. 1988); In re 
Neilson, 816 F.2d 1567, 2 U.S.P.Q.2d 1525 (Fed. Cir. 1987). Nusbaum discloses 
dynamic web page technology with no mention of broadcast user controls. Clearly there 
would be no impulse on the part of developers of dynamic web page technology to 
incorporate broadcasting user controls into dynamic web page technology. By effecting 
dynamic web page technology alone, with no hint or suggestion that broadcast user 
controls might even exist, Nusbaum teaches directly away from the combination with 
Sun proposed in the Final Office Action. Because Nusbaum teaches away from the 
applicants' claims, the proposed modification of Nusbaum with Sun cannot support a 
prima facie case of obviousness. The rejection of applicants' claims should be withdrawn 
and the case should be allowed. 

Nusbaum Cannot be a Reference Against the Claims of the Present 
Application Because Nusbaum Represents Nonanalogous Art 

Nusbaum cannot be a reference against the claims of the present application because 
Nusbaum represents nonanalogous art within the meaning of In Re Horn, Clay, and 
Oeitker. In re Horn, 203 USPQ 969 (CCPA 1979), In re Clay, 966 F.2d 656, 23 
USPQ2d 1058 (Fed. Cir. 1992), In re Oeticker, 977 F.2d 1443, 24 USPQ2d 1443 (Fed. 
Cir. 1992). The field of the inventors' effort in this case is broadcasting user controls. 
The present application claims, among other things, receiving a director instruction 
including an identification of a selected user control, extracting the selected user control, 
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identifying a data communications program, encoding in dependence upon the selected 
user control and downloading a new HTML document, and so on, as claimed in claims 1 , 
21 5 and 41 . The field of Nusbaum is dynamic web pages for the World Wide Web - 
which clearly has nothing to do with the technical field of the present application. 
Nusbaum therefore is not within the field of the inventor's endeavor in this case. 

Because Nusbaum is not within the field of the inventor's endeavor in this case, there can 
be no basis for believing that Nusbaum as a reference would have been considered by one 
skilled in the particular art working on the relevant problem to which this invention 
pertains. That is, there would be no reason for an inventor concerned with broadcasting 
user controls to search for art regarding dynamic generation of web pages. The two 
simply have nothing to do with one another. Nusbaum as a reference therefore is not 
reasonably pertinent to the particular problem with which the inventors were involved in 
the present case and is not available as a reference against the present application. 
Applicants respectfully propose that for this reason alone the rejection of the present 
claims should be withdrawn, and the claims should be allowed. 

Conclusion 

All claims in the present case stand rejected under 35 U.S.C § 103(a). Independent 
claims 1,21, and 41 stand rejected under 35 U.S.C § 103(a) over Nusbaum in view of 
Sun. The combination of Nusbaum and Sun fails to establish a prima face case of 
obviousness. The applicants have demonstrated that it is incorrect to reject the 
independent claims 1, 21, and 41 under 35 U.S.C § 103(a). The dependent claims of the 
present application include each and every element and limitation of the independent 
claims from which they depend. Because the Final Office Action cites only the 
combination of Nusbaum and Sun to teach or suggest each and every element of the 
independent claims and because all the independent claims stand, Applicants respectfully 
propose that all the dependent claims in the present case stand. The rejection of all the 
claims 1-60 should therefore be withdrawn, and the claims should be allowed. 
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Applicants respectfully traverse the rejection of claims 1-60 and request reconsideration 
of claims 1-60 in light of the present remarks. 

APPPLICANTS' RESPONSE TO EXAMINER'S RESPONSE TO APPLICANTS' 
RESPONSE TO THE FIRST OFFICE ACTION DATED SEPTEMBER 22, 2004 

The Final Office Action responds to Applicants' Response to First Office Action of 
September 22, 2004 ("First Office Action") with the following arguments. First, 
Nusbaum and Sun set forth a suggestion or motivation to combine Nusbaum and Sun. 
Second, there is a reasonable expectation of success in the combination of Nusbaum and 
Sun. Third, Nusbaum and Sun teach or suggest each and every element and limitation of 
the Applicants' claims. Finally, Nusbaum is analogous art because it is in the field of 
Applicants' endeavor or reasonably pertinent to the particular problem with which the 
Applicants were concerned. Applicants respectfully traverse each of the responses in the 
Final Office Action to Applicants' Response to the First Office Action and respond 
below in detail to the new arguments set forth in the Final Office Action. 

The Cited References Set Forth No Suggestion Or 
Motivation To Combine Nusbaum And Sun 

The Final Office Action at pages 2 and 3 argues that Nusbaum and Sun are properly 
combined for an obviousness rejection under 35 U.S.C. § 103 on the grounds that: 

Nusbaum teaches a method, a system, and a computer program product to 
implement broadcasting objects from a multiplicity of sources of digital 
information to a multiplicity of client devices (e.g., section 1.3.2. page 12) 
the method implemented in conjunction with a network of digital 
computer (e.g., figure 5, page 13), at least one of the digital computers 
comprising a content server (e.g., server containing web content, page 13) 
upon which the steps of the method are implemented in computer memory 
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and upon at least one computer processor (e.g., page 4 and section 2.1.1 .1, 
pages 31 and 32). Sun teaches well know concept of streaming digital 
content (e.g., streaming media, page 4, MPEG, JPEG, etc., video formatted 
conetent, page 6, transcoding the video contents, page 33) and to broadcast 
user controls (e.g., JMP Applet containing media controls, Appendix A, 
page 173) and that the object being used for receiving and extraction steps 
is user control (e.g., Handling of containing media controls of JMF Applet, 
Appendix A, page 173). 

That is, the Final Office Action responds to Applicants' argument that there is no 
suggestion or motivation to combine Nusbaum and Sun by stating that Nusbaum and Sun 
teach various elements and limitations of the independent claims. As explained in detail 
above, the cited references in fact do not teach broadcasting user controls for streaming 
digital content from a multiplicity of sources of digital information to a multiplicity of 
client devices as claimed in the present application. Nusbaum generally teaches a kind of 
dynamic web page technology known as Java Server Pages. What Nusbaum teaches 
specifically at section 1.3.2 is an Enterprise JavaBean™ architecture. Page 13 of 
Nusbaum specifically teaches an Enterprise JavaBean™ environment and its interaction 
with other network components. What Nusbaum teaches specifically at page 4 is an 
overview of version 2.1 of the Java Servlet API and the IBM extensions to the Servlet 
API V2. 1 . Section 2.1.1.1 of Nusbaum specifically teaches an Enterprise JavaBean™ 
server architecture. Sun generally teaches the Java Media API, an application 
programming interface for deliver of time-based media. What Sun teaches specifically at 
pages 4, 6, and 33 is a general description of streaming media and content types, common 
audio formats, and a general description of media player operations. Appendix A of Sun 
specifically teaches a Java Applet that creates a simple media player with a media event 
listener. Not only do the cited portions of the references fail to disclose or suggest 
elements of the present claims, even if they did so, the Final Office Action cannot 
arbitrarily pick and choose with massive hindsight elements of Applicants' claims from 
Java Server Pages and the Java Media API and use them as a basis to conclude the 
present claims invalid for obviousness. For these reasons, Applicants continue to assert 
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that there is no suggestion or motivation to combine Nusbaum and Sun. The proposed 
combination of Nusbaum and Sun therefore cannot support a prima facie case of 
obviousness. The rejections to claims 1-60 should be withdrawn, and the case should be 
allowed. 

The Final Office Action at page 2 citing In re Keller, 642 R2d 413, 425, 208 USPQ 871, 
881 (CCPA 1981) and In re Young, 927 F.2d 588, 591 18 USPQ2d 1089, 1091 (Fed. Cir. 
1991), also argues that: 

the test for obviousness is not whether the features of a secondary 
reference may be bodily incorporated into the structure of a primary 
reference. It is also not that the claimed invention must be expressly 
suggested in any one or all of the references. Rather, the test is what the 
combined teachings of the references would have suggested to those of 
skill in the art. 

In this way, the Final Office Action implicitly argues that there is no need for the 
Examiner to demonstrate that the references provide motivation or suggestion to combine 
or that there is any reasonable expectation of success in combining the references so long 
as elements of the present claims are disclosed in the references. 

As the Commissioner is well aware, however, such is not the law. The mere fact that 
references can be combined or modified does not render the resultant combination 
obvious unless the prior art also suggests the desirability of the combination. In re Mills, 
916 F.2d 680, 16 USPQ2d 1430 (Fed. Cir. 1990). In fact, the requirement of a prima 
facie case of obviousness places a burden on the examiner to provide some suggestion of 
the desirability of doing what the inventor has done. "To support the conclusion that the 
claimed invention is directed to obvious subject matter, either the references must 
expressly or impliedly suggest the claimed invention or the examiner must present a 
convincing line of reasoning as to why the artisan would have found the claimed 
invention to have been obvious in light of the teachings of the references." Ex parte 
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Clapp, 227 USPQ 972, 973 (Bd. Pat. App. & Inter. 1985). When the motivation to 
combine the teachings of the references is not immediately apparent, it is the duty of the 
examiner to explain why the combination of the teachings is proper. Ex parte Skinner ', 2 
USPQ2d 1788 (Bd. Pat. App. & Inter. 1986); MPEP § 2142. 

The Final Office Action merely continues the practice begun in the First Office Action of 
pointing to elements of method and system in its cited references and stating that they are 
the same things claimed in the present patent application. The Final Office Action makes 
no substantive attempt whatsoever to present a prima facie case of obviousness by 
pointing to express or implicit suggestion to combine in the references themselves or by 
explaining or providing any basis for concluding that persons of skill in the art would be 
moved to combine the references. For these reasons also, Applicants continue to assert 
that the cited references do not contain a suggestion or motivation to combine. The 
proposed combination of Nusbaum and Sun therefore cannot support a prima facie case 
of obviousness. The rejections to claims 1-60 should be withdrawn, and the case should 
be allowed. 

There Is No Reasonable Expectation Of Success In The 
Combination Of Nusbaum And Sun 

In response to Applicants' Response to the First Office Action, the Final Office Action at 
pages 3 and 4 argues that there is a reasonable expectation of success in the combination 
of Nusbaum and Sun. The Final Office Action does not, however, provide any new basis 
for this assertion other than stating that Nusbaum and Sun teach various elements and 
limitations of the independent claims. As explained in detail above, the cited references 
in fact do not teach broadcasting user controls for streaming digital content from a 
multiplicity of sources of digital information to a multiplicity of client devices as claimed 
in the present application. Nusbaum generally teaches a kind of dynamic web page 
technology known as Java Server Pages. Sun generally teaches the Java Media API, an 
application programming interface for delivery of time-based media. The dynamic web 
page technology of Nusbaum for building adhoc server pages is not related to the Java 
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API for time-based media of Sun. In fact, the technology for building dynamic web 
pages is entirely different from a Java API for time-based media. JSPs generate 
documents viewable in a web browser, while the API for time-based media provide a 
Java class architecture to software developers. Combining Nusbaum's Java Server Pages 
and Sun's Java Media API does not provide broadcasting user controls for streaming 
digital content from a multiplicity of sources of digital information to a multiplicity of 
client devices as claimed in the present application. For these reasons, Applicants 
continue to assert that there is therefore no reasonable expectation of success in the 
proposed combination of Nusbaum and Sun. The proposed combination of Nusbaum and 
Sun therefore cannot support a prima facie case of obviousness. The rejections to claims 
1-60 should be withdrawn, and the case should be allowed. 



Nusbaum And Sun Do Not Teach 
Each and Every Element of the Claim 



The Final Office Action at pages 4 and 5 again argues that Nusbaum and Sun teach each 
and every element of independent claims 1,21, and 41 by reciting portions of Nusbaum 
and Sun mentioned above in this Brief. To establish a prima facie case of obviousness, 
the proposed combination of Nusbaum and Sun must teach all of Applicants' claim 
limitations. In re Royka, 490F.2d 981, 985, 180 USPQ 580, 583 (CCPA 1974). As 
discussed in detail above, the combination of Nusbaum and Sun does not teach each and 
every element of the independent claims in the present case. The Final Office Action 
therefore cannot establish a prima facie case for obviousness of claims 1,21, and 41 
under 35 U.S.C. § 103. The dependent claims of the present application include each and 
every element and limitation of the independent claims from which they depend. 
Because the Final Office Action cites only the combination of Nusbaum and Sun to teach 
or suggest each and every element of the independent claims and because all the 
independent claims stand, Applicants respectfully propose that all the dependent claims 
in the present case stand. The proposed combination of Nusbaum and Sun therefore 
cannot support a prima facie case of obviousness. The rejections to claims 1-60 should 
be withdrawn, and the case should be allowed. 
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Nusbaum Is Not Analogous Art Because It Is Neither In The Field Of Applicants' 
Endeavor Nor Reasonably Pertinent To The Particular Problem 
With Which The Applicants Were Concerned 



In response to Applicants' First Office Action, the Final Office Action at pages 6 and 7 
argues that Nusbaum is analogous art available for rejecting the claims of the present 
application. The Final Office Action asserts that Nusbaum is in the field of Applicants' 
endeavor or reasonably pertinent to the particular problem with which the Applicants 
were concerned. In support for this assertion, the Final Office Action at page 6 and 7 
only states that Nusbaum and Sun teach various elements and limitations of the 
independent claims. As explained in detail above, the cited references in fact do not 
teach broadcasting user controls for streaming digital content from a multiplicity of 
sources of digital information to a multiplicity of client devices as claimed in the present 
application. Nusbaum generally teaches a kind of dynamic web page technology known 
as Java Server Pages. Sun generally teaches the Java Media API, an application 
programming interface for delivery of time-based media. Without more, Nusbaum's Java 
Server Pages does not place Nusbaum in the field of Applicants' endeavor or make 
Nusbaum reasonably pertinent to the particular problem with which the Applicants were 
concerned, such concern being, broadcasting user controls for streaming digital content 
from a multiplicity of sources of digital information to a multiplicity of client devices as 
claimed in the present application. 

In addition, Applicants respectfully propose that Nusbaum cannot be a reference against 
the claims of the present application because Nusbaum actually represents nonanalogous 
art within the meaning of In Re Horn, Clay, and Oeitker. In re Horn, 203 USPQ 969 
(CCPA 1979), In re Clay, 966 F.2d 656, 23 USPQ2d 1058 (Fed. Cir. 1992), In re 
Oeticker, 977 F.2d 1443, 24 USPQ2d 1443 (Fed. Cir. 1992). The field of the inventors' 
effort in this case is broadcasting user controls for streaming digital content from a 
multiplicity of sources of digital information to a multiplicity of client devices. The 
present application claims, among other things, receiving a director instruction, extracting 
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a user control, identifying a data communications program based on the director 
instruction, and encoding new HTML document based on the user control. The field of 
Nusbaum is dynamic web pages for the World Wide Web - which clearly has nothing to 
do with the technical field of the present application. Nusbaum therefore is not within the 
field of the inventor's endeavor in this case. 

Because Nusbaum is not within the field of the inventor's endeavor in this case, there can 
be no basis for believing that Nusbaum as a reference would have been considered by one 
skilled in the particular art working on the relevant problem to which this invention 
pertains. That is, there would be no reason for an inventor concerned with broadcasting 
user controls for streaming digital content to search for art regarding dynamic generation 
of web pages. The two simply have nothing to do with one another. Nusbaum as a 
reference therefore is neither within the field of the Applicants' endeavor nor reasonably 
pertinent to the particular problem with which the inventors were involved in the present 
case. Nusbaum therefore is not available as a reference against the present application. 
Applicants respectfully propose that for this reason alone the rejection of the present 
claims 1-60 should be withdrawn, and the claims should be allowed. 

Conclusion 

Applicants traverse each of the arguments in the Final Office Action responding to 
Applicants' Response to First Office Action. Applicants demonstrate that the cited 
references in the Final Office Action set forth neither a suggestion nor motivation to 
combine Nusbaum and Sun. Furthermore, there is no reasonable expectation of success 
in the combination of Nusbaum and Sun. In addition, Nusbaum and Sun do not teach or 
suggest each and every element and limitation of the Applicants' claims. Applicants also 
demonstrate that Nusbaum represents nonanalogous art. Applicants' therefore 
respectfully traverse each rejection individually of claims 1-60. 
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In view of the forgoing arguments, reversal on all grounds of rejection is requested. 



The Commissioner is hereby authorized to charge or credit Deposit Account No. 09-0447 
for any fees required or overpaid. 



Date: November 30. 2005 



Respectfully submitted, 




-^John Biggers ^ 
Reg. No. 44,537 
Biggers & Ohanian, LLP 
P.O. Box 1469 
Austin, Texas 78767-1469 
Tel. (512) 472-9881 
Fax (512) 472-9887 
ATTORNEY FOR APPELLANTS 
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APPENDIX OF CLAIMS 
ON APPEAL IN PATENT APPLICATION OF 
WILLIAM K. BODIN, ETAL., SERIAL NO. 09/881,917 

CLAIMS 

What is claimed is: 

1 . A method of broadcasting user controls for streaming digital content from a 

multiplicity of sources of digital information to a multiplicity of client devices, 
the method implemented in conjunction with a network of digital computers, at 
least one of the digital computers comprising a content server upon which the 
steps of the method are implemented in computer memory and upon at least one 
computer processor, the method comprising the steps of: 

receiving from a remote director a director instruction, the director instruction 
comprising an identification of a selected user control; 

extracting, in dependence upon the director instruction, from a store of user 
controls, the identified selected user control; 

identifying, in dependence upon the director instruction, a data communications 
program that administers data communications between the content server and a 
client device; 

encoding through the data communications program, in dependence upon the 
selected user control, a new HTML document; and 
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downloading, through the identified data communications program, the new 
HTML document to the client device. 

2. The method of claim 1, wherein the remote director comprises a computer 
coupled for data communications to the content server, the remote director further 
comprising a browser. 

3. The method of claim 1 wherein the director instruction comprises a director URL, 
the director URL comprising an indication that the director URL is a user control 
broadcast instruction, the director URL further comprising an identification of the 
selected user control to be broadcast. 

4. The method of claim 1 wherein the store of user controls comprises a multiplicity 
of user control data records each of which represents a single user control and 
each of which further comprises a user control URL. 

5. The method of claim 4 wherein each user control data record further comprises a 
data element that identifies a computer program that gives effect to a user control. 

6. The method of claim 1 wherein extracting, in dependence upon the director 
instruction, from a store of user controls, the selected user control, further 
comprises searching a store of user controls for a user control identified in the 
director instruction. 

7. The method of claim 1 wherein the director instruction further comprises a 
director URL, and extracting the selected user control further comprises searching 
a store of user controls for a user control identified in the director URL. 
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8. The method of claim 1 wherein identifying, in dependence upon the director 
instruction an identified data communications program that administers data 
communications with a client device further comprises executing a user control 
selection routine that itself is identified in the director instruction. 

9. The method of claim 1 wherein the director instruction further comprises a 
director URL, and wherein identifying, in dependence upon the director 
instruction, an identified data communications program that administers data 
communications with a client device further comprises executing a user control 
selection routine that itself is identified in the director URL. 

10. The method of claim 9 wherein executing a user control selection routine further 
comprises passing to the user control selection routine a parameter identifying the 
selected user control. 

1 1 . The method of claim 9 wherein executing a user control selection routine further 
comprises passing to the user control selection routine a parameter identifying a 
subscription level. 

12. The method of claim 9 wherein executing a user control selection routine further 
comprises passing to the user control selection routine a parameter identifying 
user preferences. 

13. The method of claim 9 wherein executing a user control selection routine further 
comprises passing to the user control selection routine a parameter identifying 
user demographics. 

14. The method of claim 9 wherein executing a user control selection routine further 
comprises passing to the user control selection routine a parameter identifying a 
client device type. 
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15. The method of claim 1 wherein encoding, within the identified data 
communications program, in dependence upon the selected user control, a new 
HTML document, further comprises encoding the selected user control as a 
hyperlink and formulating the new HTML document to include the hyperlink. 

16. The method of claim 1 wherein the new HTML document comprises an old 
HTML document further including the hyperlink. 

1 7. The method of claim 1 wherein the old HTML document is the HTML document 
that was displayed on the client device just before downloading the new HTML 
document to the client device. 

18. The method of claim 1 wherein the selected user control further comprises a 
duration. 

1 9. The method of claim 1 8 further comprising timing the duration of the user 
control. 

20. The method of claim 1 9 further comprising restoring to the client device, after 
timing the duration of the selected user control, an old HTML document 
comprising an HTML document that was previously displayed on the client 
device before downloading the new HTML document to the client device. 

21. A system for broadcasting user controls for streaming digital content from a 
multiplicity of sources of digital information to a multiplicity of client devices, 
the system implemented in conjunction with a network of digital computers, at 
least one of the digital computers comprising a content server upon which the 
principal elements of the system are implemented, including computer memory 
and at least one computer processor, the system comprising: 
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means for receiving from a remote director a director instruction, the director 
instruction comprising an identification of a selected user control; 

means for extracting, in dependence upon the director instruction, from a store of 
user controls, the identified selected user control; 

means for identifying, in dependence upon the director instruction, a data 
communications program that administers data communications between the 
content server and a client device; 

means for encoding through the data communications program, in dependence 
upon the selected user control, a new HTML document; and 

means for downloading, through the identified data communication program, the 
new HTML document to the client device. 

22. The system of claim 2 1 , wherein the remote director comprises a computer 
coupled for data communications to the content server, the remote director further 
comprising a browser. 

23. The system of claim 21 wherein the director instruction comprises a director 
URL, the director URL comprising an indication that the director URL is a user 
control broadcast instruction, the director URL further comprising an 
identification of the selected user control to be broadcast. 

24. The system of claim 21 wherein the store of user controls comprises a multiplicity 
of user control data records each of which represents a single user control and 
each of which further comprises a user control URL. 



25. 



The system of claim 24 wherein each user control data record further comprises a 
data element that identifies a computer program that gives effect to a user control. 
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26. The system of claim 21 wherein means for extracting, in dependence upon the 
director instruction, from a store of user controls, the selected user control, further 
comprises means for searching a store of user controls for a user control identified 
in the director instruction. 

27. The system of claim 21 wherein the director instruction further comprises a 
director URL, and means for extracting the selected user control further comprises 
means for searching a store of user controls for a user control identified in the 
director URL. 

28. The system of claim 21 wherein means for identifying, in dependence upon the 
director instruction an identified data communications program that administers 
data communications with a client device further comprises means for executing a 
user control selection routine that itself is identified in the director instruction. 

29. The system of claim 21 wherein the director instruction further comprises a 
director URL, and wherein means for identifying, in dependence upon the director 
instruction, an identified data communications program that administers data 
communications with a client device further comprises means for executing a user 
control selection routine that itself is identified in the director URL. 

30. The system of claim 29 wherein means for executing a user control selection 
routine further comprises means for passing to the user control selection routine a 
parameter identifying the selected user control. 

3 1 . The system of claim 29 wherein means for executing a user control selection 
routine further comprises means for passing to the user control selection routine a 
parameter identifying a subscription level. 

32. The system of claim 29 wherein means for executing a user control selection 
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routine further comprises means for passing to the user control selection routine a 
parameter identifying user preferences. 

33. The system of claim 29 wherein means for executing a user control selection 
routine further comprises means for passing to the user control selection routine a 
parameter identifying user demographics. 

34. The system of claim 29 wherein means for executing a user control selection 
routine further comprises means for passing to the user control selection routine a 
parameter identifying a client device type. 

35. The system of claim 21 wherein means for encoding, within the identified data 
communications program, in dependence upon the selected user control, a new 
HTML document, further comprises means for encoding the selected user control 
as a hyperlink and means for formulating the new HTML document to include the 
hyperlink. 

36. The system of claim 21 wherein the new HTML document comprises an old 
HTML document further including the hyperlink. 

37. The system of claim 21 wherein the old HTML document is the HTML document 
that was displayed on the client device just before downloading the new HTML 
document to the client device. 

38. The system of claim 21 wherein the selected user control further comprises a 
duration. 

39. The system of claim 38 further comprising means for timing the duration of the 
user control. 

40. The system of claim 39 further comprising means for restoring to the client device 
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an old HTML document comprising an HTML document that was previously 
displayed on the client device before a downloading of the new HTML document 
to the client device. 

A computer program product for broadcasting user controls for streaming digital 
content from a multiplicity of sources of digital information to a multiplicity of 
client devices, the computer program product prepared for implementation in 
conjunction with a network of digital computers, at least one of the digital 
computers comprising a content server upon which the principal elements of the 
computer program product are implemented, including computer memory and at 
least one computer processor, the computer program product comprising: 

a recording medium; 

means, recorded on the recording medium, for receiving from a remote director a 
director instruction, the director instruction comprising an identification of a 
selected user control; 

means, recorded on the recording medium, for extracting, in dependence upon the 
director instruction, from a store of user controls, the identified selected user 
control; 

means, recorded on the recording medium, for identifying, in dependence upon 
the director instruction, a data communications program that administers data 
communications between the content server and a client device; 

means, recorded on the recording medium, for encoding through the data 
communications program, in dependence upon the selected user control, a new 
HTML document; and 
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means, recorded on the recording medium, for downloading, through the 
identified data communication program, the new HTML document to the client 
device. 

42. The computer program product of claim 41, wherein the remote director 
comprises a computer coupled for data communications to the content server, the 
remote director further comprising a browser. 

43. The computer program product of claim 41 wherein the director instruction 
comprises a director URL, the director URL comprising an indication that the 
director URL is a user control broadcast instruction, the director URL further 
comprising an identification of the selected user control to be broadcast. 

44. The computer program product of claim 41 wherein the store of user controls 
comprises a multiplicity of user control data records each of which represents a 
single user control and each of which further comprises a user control URL. 

45. The computer program product of claim 44 wherein each user control data record 
further comprises a data element that identifies a computer program that gives 
effect to a user control. 

46. The computer program product of claim 41 wherein means for extracting, in 
dependence upon the director instruction, from a store of user controls, the 
selected user control, further comprises means, recorded on the recording 
medium, for searching a store of user controls for a user control identified in the 
director instruction. 

47. The computer program product of claim 41 wherein the director instruction 
further comprises a director URL, and means for extracting the selected user 
control further comprises means, recorded on the recording medium, for searching 
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a store of user controls for a user control identified in the director URL. 

48. The computer program product of claim 41 wherein means for identifying, in 
dependence upon the director instruction an identified data communications 
program that administers data communications with a client device further 
comprises means, recorded on the recording medium, for executing a user control 
selection routine that itself is identified in the director instruction. 

49. The computer program product of claim 41 wherein the director instruction 
further comprises a director URL, and wherein means for identifying, in 
dependence upon the director instruction, an identified data communications 
program that administers data communications with a client device further 
comprises means, recorded on the recording medium, for executing a user control 
selection routine that itself is identified in the director URL. 

50. The computer program product of claim 49 wherein means for executing a user 
control selection routine further comprises means, recorded on the recording 
medium, for passing to the user control selection routine a parameter identifying 
the selected user control. 

5 1 . The computer program product of claim 49 wherein means for executing a user 
control selection routine further comprises means, recorded on the recording 
medium, for passing to the user control selection routine a parameter identifying a 
subscription level. 

52. The computer program product of claim 49 wherein means for executing a user 
control selection routine further comprises means, recorded on the recording 
medium, for passing to the user control selection routine a parameter identifying 
user preferences. 

53. The computer program product of claim 49 wherein means for executing a user 
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control selection routine further comprises means, recorded on the recording 
medium, for passing to the user control selection routine a parameter identifying 
user demographics. 

54. The computer program product of claim 49 wherein means for executing a user 
control selection routine further comprises means, recorded on the recording 
medium, for passing to the user control selection routine a parameter identifying a 
client device type. 

55. The computer program product of claim 41 wherein means for encoding, within 
the identified data communications program, in dependence upon the selected 
user control, a new HTML document, further comprises means, recorded on the 
recording medium, for encoding the selected user control as a hyperlink and 
means, recorded on the recording medium, for formulating the new HTML 
document to include the hyperlink. 

56. The computer program product of claim 41 wherein the new HTML document 
comprises an old HTML document further including the hyperlink. 

57. The computer program product of claim 41 wherein the old HTML document is 
the HTML document that was displayed on the client device just before a 
downloading of the new HTML document to the client device. 

58. The computer program product of claim 41 wherein the selected user control 
further comprises a duration. 

59. The computer program product of claim 58 further comprising means, recorded 
on the recording medium, for timing the duration of the user control. 

60. The computer program product of claim 59 further comprising means, recorded 
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on the recording medium, for restoring to the client device an old HTML 
document comprising an HTML document that was previously displayed on the 
client device before a downloading of the new HTML document to the client 
device. 
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Abstract. This paper presents OpenJava, which is a macro system that 
we have developed for Java. With traditional macro systems designed for 
non object-oriented languages, it is difficult to write a number of macros 
typical in object-oriented programming since they require the ability to 
access a logical structure of programs. One of the drawbacks of tradi- 
tional macro systems is that abstract syntax trees are used for repre- 
senting source programs. This paper first points out this problem and 
then shows how OpenJava addresses this problem. A key idea of Open- 
Java is to use metaobjects, which was originally developed for reflective 
computing, for representing source programs. 

1 Introduction 

Reflection is a technique for changing the program behavior according to another 
program. Prom software engineering viewpoint, reflection is a tool for separation 
of concerns and thus it can be used for letting programmers write a program 
with higher-level abstraction and with good modularity. For example, a number 
of reflective systems provide metaobjects for intercepting object behavior, that 
is, method invocations and field accesses. Those metaobjects can be used for 
weaving several programs seprately written from distinct aspects, such as an 
application algorihtm, distribution, resource allocation, and user interface, into 
a single executable program. 

However, previous reflective systems do not satisfy all the requirements in 
software engineering. Although the abstraction provided by the metaobjects for 
intercepting object behavior is easy to understand and use, they can be used for 
implementing only limited kinds of separation of concerns. Moreover, this type 
of reflection often involves runtime penalties. Reflective systems should enable 
more fine-grained program weaving and perform as much reflective computation 
as possible at compile time for avoiding runtime penalities. 

On the other hand, a typical tool for manipulating a program at compile time 
has been a macro system. It performs textual substitution so that a particualr 
aspect of a program is separated from the rest of that program. For example, 
the C/C++ macro system allows to separate the definition of a constant value 



from the rest of a program, in which that constant value is used in a number 
of distinct lines. The Lisp macro system provides programmable macros, which 
enables more powerful program manipulation than the C/C++ one. Also, since 
macro expansion is done at compile time, the use of macros does not imply any 
runtime penalties. However, the abstraction provided by traditional macro sys- 
tems is not sophisticated; since macros can deal with only textual representation 
of a program, program manipulation depending on the semantic contexts of the 
program cannot be implemented with macros. 

This paper proposes a macro system integrating good features of the reflective 
approach, in other words, a compile-time reflective system for not only behav- 
ioral reflection but also structural reflection. A key idea of our macro system, 
called OpenJava, is that macros (meta programs) deal with class metaobjects 
representing logical entities of a program instead of a sequence of tokens or ab- 
stract syntax trees (ASTs). Since the class metaobjects abstract both textual 
and semantic aspects of a program, macros in OpenJava can implement more 
fine-grained program weaving than in previous reflective systems. They can also 
access semantic contexts if they are needed for macro expansion. This paper 
presents that OpenJava can be used to implement macros for helping complex 
programmings with a few design patterns. 

In the rest of this paper, section 2 presents a problem of ordinary macro sys- 
tems and section 3 discusses the design and implementation of OpenJava, which 
addresses this problem. We compare OpenJava with related work in section 4. 
Finally, section 5 concludes this paper. 



2 Problems with Ordinary Macros 

Macro systems have been typical language-extension mechanisms. With C/C++ 's 
#def ine macro system, programmers can specify a symbol or a function call to 
be replaced with another expression, although this replacement is simple token- 
based substitution. In Common Lisp, programmers can write more powerful 
macros. However, even such powerful macros do not cover all requirements of 
00 languages programming. 



2.1 Programmable Macros 

Macros in Common Lisp are programmable macros. They specify how to replace 
an original expression in Common Lisp itself. A macro function receives an 
AST (abstract syntax tree) and substitutes it for the original expression. Since 
this macro system is powerful, the object system of Common Lisp (CLOS) is 
implemented with this macro system. 

Programmable macros have been developed for languages with more complex 
syntax like C. MS 2 [19] is one of those macro systems for C. Macro functions are 
written in an extended C language providing special data structure representing 
ASTs. The users of MS 2 can define a new syntax and how it is expanded into 



a regular C syntax. The parameter that a macro function receives is an AST of 
the code processed by that macro function. 

One of the essential issue in designing a programmable macro system is a 
data structure representing an original source program. Another essential issue 
is how to specify where to apply each macro in a source program. For the former 
most systems employed ASTs. For the latter, several mechanisms were proposed! 

In Common Lisp and MS 2 , a macro is applied to expressions or statements 
beginning with the trigger word specified by the macro. For example, if the 
trigger word is unless, all expressions beginning with unless are expanded by 
that macro. In this way, they cannot use macros without the trigger words. For 
instance, it is impossible to selectively apply a macro to only + expressions for 
adding string objects. 

Some macro systems provide fine-grained control of where to apply a macro. 
In A* [14], a macro is applied to expressions or statements matching a pattern 
specified in the BNF. In EPP[9], macros are applied to a specified syntax ele- 
ments like if statements or + expressions. There's no need to put any trigger 
word in front of these statements or expressions. 



2.2 Representation of Object-Oriented Programs 

Although most of macro systems have been using ASTs for representing a source 
program, ASTs are not the best representation for all macros; some macros typ- 
ical in 00 programming require a different kind of representation. ASTs are 
purely textual representation and independent of logical or contextual informa- 
tion of the program. For example, if an AST represents a binary expression, the 
AST tells us what the operator and the operands are but it never tells us the 
types of the operands. Therefore, writing a macro is not possible with ASTs 
if the macro expansion depends on logical and contextual information of that 
binary expression. 

There is a great demand for the macros depending on logical and contextual 
information in 00 programming. For example, some of design patterns[6] re- 
quire relatively complicated programming. They often require programmers to 
repeatedly write similar code.[l] To help this programrriing, several researchers 
have proposed to extend a language to provide new language constructs special- 
ized for particular patterns [1, 7], Those constructs should be implemented with 
macros although they have been implemented so far by a custom preprocessor. 
This is because macros implementing those constructs depend on the logical and 
contextual information of programs and thus they are not implementable on top 
of the traditional AST-based macro systems. 

Suppose that we write a macro for helping prograniming with the Ob- 
server^] pattern, which is for describing one-to-many dependency among ob- 
jects. This pattern is found in the Java standard library although it is called 
the event-and-listener model. For example, a Java program displays a menu bar 
must define a listener object notified of menu-select events. The listener object 
is an instance of a class My Menu Listener implementing interface MenuListener: 



class MyMenuListener implements MenuListener { 
void menuSelected(MenuEvent e) { . . > 
void menuDe select ed(MenuEvent e) { return; } 
void menuCanceled(MenuEvent e) { return; > 

This class must declare aU the methods for event handling even though some 
events, such as the menu cancel event, are simply ignored. 

We write a macro for automating declaration of methods for handling ignored 
events. If this macro is used, the definition of MyMenuListener should be re- 
written into: 

class MyMenuListener follows ObserverPattern 
implements MenuListener 

{ 

void menuSelected(MenuEvent e) { . . } 

} 

The follows clauses specifies that our macro ObserverPattern is applied to this 
class definition. The declarations of menuDeselectedO and menuCanceled () are 
automated. This macro first inspects which methods declared in the interface 
MenuListener are not implemented in the class MyMenuListener. Then it inserts 
the declarations of these methods in the class MyMenuListener. 

Writing this macro is difficult with traditional AST-based macro systems 
since it depends on the logical information of the definition of the class My- 
MenuListener. If a class definition is given as a large AST, the macro program 
must interpret the AST and recognize methods declared in MenuListener and 
MyMenuListener. The macro program must also construct ASTs representing 
the inserted methods and modify the original large AST to include these ASTs. 
Manipulating a large AST is another difficult task. Tb reduce these difficulties, 
macro systems should provide logical and contextual information of programs 
for macro programs. There are only a few macro systems providing the logical 
information. For example, XL[15] is one of those systems although it is for a 
functional language but not for an 00 language. 



3 OpenJava 

OpenJava is our advanced macro system for Java. In OpenJava, macro programs 
can access the data structures representing a logical structure of the programs. 
We call these data structure class metaobjects. This section presents the design 
of OpenJava. 



3.1 Macro Programming in OpenJava 

OpenJava produces an object representing a logical structure of class definition 
for each class in the source code. This object is called a class metaobject. A class 



metaobject also manages macro expansion related to the class it represents. Pro- 
grammers customize the definition of the class metaobjects for describing macro 
expansion. We call the class for the class metaobject metaclass. In OpenJava, 
the metaprogram of a macro is described as a metaclass^ Macro expansion by 
OpenJava is divided into two: the first one is macro expansion of class decla- 
rations (callee-side), and the second one is that of expressions accessing classes 
(caller-side). 

Applying Macros Fig. 1 shows a sample using a macro in OpenJava. By 
adding a clause instantiates M in just after the class name in a class declara- 
tion, the programmer can specify that the class metaobject for the class is an 
instance of the metaclass M. In this sample program, the class metaobject for 
MyMenuListener is an instance of ObserverClass. This metaobject controls macro 
expansion involved with MyMenuListener. The declaration of ObserverClass is 
described in regular Java as shown in Fig. 2. 

class MyMenuListener 

instantiates ObserverClass 

extends MyObjoct 

implements MenuListener 
{ .... } 



Fig. 1. Application of a macro in OpenJava 



class ObserverClass 
extends OJClass 

{ 

void translateDef init ion O { . . . > 



Fig. 2. A macro in OpenJava 



Every metaclass must inherit from the metaclass OJClass, which is a built-in 
class of OpenJava. The translateDef init ion () in Fig. 2 is a method inherited 
from OJClass, which is invoked by the system to make macro expansion. If an 
instantiates clause in a class declaration is found, OpenJava creates an in- 
stance of the metaclass indicated by that instantiates clause, and assigns this 
instance to the class metaobject representing that declared class. Then Open- 
Java invokes translateDef init ion () on the created class metaobject for macro 
expansion on the class declaration later. 



Since the translateDefinitionO declared in OJCIass does not perform 
any translation, a subclass of OJCIass must override this method for the desired 
macro expansion. For example, translateDefinitionO can add new member 
methods to the class by calling other member methods in OJCIass. Modifications 
are reflected on the source program at the final stage of the macro processing. 

Describing a Metaprogram The method translateDefinitionO imple- 
menting the macro for the Observer pattern in section 2.2 is shown in Fig. 3. 
This metaprogram first obtains all the member methods (including inherited 
ones) defined in the class by invoking getMethodsO on the class metaobject. 
Then, if a member method declared in interfaces is not implemented in the class, 
it generates a new member method doing nothing and adds it to the class by 
invoking addMethodO on the class metaobject. 

void translateDefinitionO { 

OJMethodD m - this. getKetfcodsC this ) ; 
for (int i ** 0; i < m. length; ++i) { 

OJNodifiar nodif - n[i] .getModif iersO ; 
if (modif .isAbatractO) { 

OJHethod n « amr 0JMethod(thie, 

a Ci] . gstModif iers 0 . renoveAbstract ( ) , 
ffi[i] .getEteturntypeO , n[i] .get Name O , 
nti] .getParametertypesO , 
m Ci] . gotEzceptioniypes () , 
aakeStatementUstCretnm; ')) ; 
this.addMathodCn); 

> 

> 

> 



Fig. 3. translateDefinitionO in ObserverClass 

As a class is represented by a class metaobjects, a member method is also 
represented by a method metaobjects. In OpenJava, classes, member methods, 
member fields, and constructors are represented by instances of the class OJCIass, 
0 J Method, 0 J Field, and 0 J Constructor, respectively. These metaobject represent 
logical structures of class and member definitions. They are easy to handle, 
compared to directly handling large ASTs representing class declarations and 
collecting information scattered in these ASTs. 

3.2 Class Metaobjects 

As shown in section 2, a problem of ordinary macro systems is that their pri- 
mary data structure is ASTs (abstract syntax trees) but they are far from logical 
sturctures of programs in 00 languages. In 00 languages like Java, class def- 
initions play an important role as a logical structure of programs. Therefore, 
OpenJava employs the class metaobjects model, which was originally developed 
for reflective computing, for representing a logical structure of a program. The 



class metaobjects make it easy for meta programs to access a logical structure 
of program. 

Hiding Syntactical Information In Java, programmers can use various syn- 
tax for describing the logically same thing. These syntactical differences are 
absorbed by the metaobjects. For instance, there are two notations for declaring 
a String array member field: 

String □ a; 
String b[]; 

Both a and b are String array fields. It would be awkward to write a metapro- 
gram if the syntactical differences of the two member fields had to be considerd. 
Thus OJField provides only two member methods getTypeO and setTypeO 
for handling the type of a member field. getTypeO on the OJField metaobjects 
representing a and b returns a class metaobject representing the array type of 
the class String. 

Additionally, some elements in the grammer represent the same element in 
a logical structure of the language. If one of these element is edited, the others 
are also edited. For instance, the member method setNameO in O J Class for 
modifying the name of the class changes not only the class name after the class 
keyword in the class declaration but also changes the name of the constructors. 

Logically Structured Class Representation Simple ASTs, even arranged 
and abstracted well, cannot properly represent a logical structure of a class 
definition. The data structure must be carefully designed to corresponded not 
only to the grammer of the language but also to the logical constructs of the 
language like classes and member methods. Especially, it makes it easy to handle 
the logical information of program including association between names and 
types. 

For instance, the member method getMethodsO in OJCIass returns all the 
member methods defined in the class which are not only the methods immedi- 
ately declared in the class but also the inherited methods. The class metaobjects 
contain type information so that the definition of the super class can be acces- 
sible. 

3.3 Class Metaobjects in Details 

The root class for class metaobjects is OJCIass. The member methods of OJCIass 
for obtaining information about a class are shown in Tab. 1 and Tab. 2. They 
cover all the attributes of the class. In OpenJava, all the types, including array 
types and primitive types like int, have corresponding class metaobjects. Using 
the member methods shown in Tab. 1, metaprogramms can inspect whether a 
given type is an ordinary class or not. 

Tab. 3 gives methods for modifying the definition of the class. Metaprograms 
can override translateDef initionO in OJCIass so that it calls these methods 



for executing desired modifications. For instance, the example shown in Pig. 3 
adds newly generated member methods to the class with addMethodQ . 



Table 1. Member Methods in OJCIass for Non-Class Types 



boolean isInterfaceO 

Tests if this represents an interface type, 
boolean isArrayO 

Tests if this represents an array type, 
boolean isPrinitiveC) 

Tests if this represents an premitive type. 
OJCIass get Component Type 0 

Returns a class metaobject for the type of array components. 



Metaobjects Obtained through Class Metaobjects The method getSuper class () 
in OJCIass, which is used to obtain the superclass of the class, returns a class 
metaobject instead of the class name (as a string). As the result, metaprogram 
can use the returned class metaobject to directly obtain information about the 
superclass. OpenJava automatically generates class metaobjects on demand, 
even for classes declared in another source file or for classes available only in 
the form of bytecode, that is, classes whose source code is not available. 

The returned value of the member method getModif iersO in Tab. 2 is an 
instance of the class 0 J Modifier. This class represents a set of class modifiers 
such as public, abstract or final. Metaprogramms do not have to care about 
the order of class modifiers because 0 J Modifier hides such useless information. 

The class OJMethod, which is the return type of getDeclaredMethods () 
in OJCIass, represents a logical structure of a method. Thus, similarly to the 
class OJCIass, this class has member methods for examining or modifying the 
attributes of the method. Some basic member methods in OJMethod axe shown in 
Tab. 4. Any type information obtained from these methods is also represented by 
a class metaobject. For instance, getReturnTypeO returns a class metaobject 
as the return type of the method. This feature of OJMethod is also found in 
0 J Field and OJConstructor, which respectively represent a member field and a 
constructor. 

The class StatementList, which is the return type of the member method 
getBodyO in the class OJMethod, represents the statements in a method body. 
An instance of StatementList consists of objects representing either expressions 
or statements. StatementList objects are AST-like data structures although they 
contain type information. This is because we thought that the logical structure 
of statements and expressions in Java can be well represented with ASTs. 



Table 2. Member Methods in OJClass for introspection (1) 



String getPackageNaneO 

Returns the package name this class belongs to. 
String gatSissploHameO 

Returns the unqualified name of this class. 

OJModifier getModif iersO 

Returns the modifiers for this class. 
OJClass getSuperclassO 

Returns the superclass declared explicitly or implicitly. 

OJClass □ getDeclaredXnterfacesO 

Returns all the declared superinterfoces. 

StatementList getlnitializerO 

Returns all the static initializer statements. 
OJFieldD gatDeclaredFieldsO 

Returns all the declared fields. 
OJMethod □ getDeclaredMethodsO 

Returns all the declared methods. 
DJConctructorO getDeclaredCcnstructors C) 

Returns all the constructors declared explicitly or implicitly. 

OJClass D gatDeclaredClassesO 

Returns ail the member classes (inner classes). 

OJClass getDeclaringClassO 

Returns the class declaring this class (outer class). 



T&ble 3. Member Methods in OJClass for modifying the class 



String eetSimplename (String nana) 

Sets the unqualified name of this class. 

OJModif ier setModif iers(DJHodifier oodife) 
Sets the class modifiers. 

OJClass satSuperclass (0 JCl&ss clazz) 
Sets the superclass. 

OJClass □ s«t Interfaces (OJClass □ faces) 
Sets the super interfaces to be declared. 

OJField renovoFieldCOJField field) 

Removes the given field from this class declaration. 

OJMethod removoMethod (OJMethod method) 

Removes the given method from this class declaration. 

DJConstmctor removeConstrtictorCOJConstructor constr) 

Removes the given constructor from this class declaration. 

OJField addField (OJField field) 

Adds the given field to this class declaration. 

OJMethod addMethod (OJMethod method) 

Adds the given method to this class declaration. 

OJConstrnctor addConstructor (0 JConstructor constr) 
Adds the given constructor to this class declaration. 



Table 4. Basic Methods in OJMethod 



String getHaaeO 

Returns the name of this method. 
DJHodifier gatModif iersO 

Returns the modifiers for this method. 
OJClass getfteturaTypoO 

Returns the return type. 

OJClass □ getParaneterTypesO 

Returns the parameter types in declaration order. 
OJClass □ getExcoptionTypesO 

Returns the types of the exceptions declared to be thrown. 
String [] getParaoeter Variables ( ) 

Returns the parameter variable names in declaration order. 
StatenentList got Body () 

Returns the statements of the method body. 
String settfaae (String name) 

Sets the name of this method. 
OJModifiar setModif iors (DJModif iar modifs) 

Sets the method modifiers. 
OJClass setRetuxnTypeO 

Sets the return type. 

OJClass D setParameterTypesO 

Sets the parameter types in declaration order. 

OJClass 0 setExceptianTypesC) 

Sets the types of the exceptions declared to be thrown. 

String [] setParameterVariablesO 

Sets the parameter variable names in declaration order. 
StatementList setBodyO 

Sets the statements of the method body. 



Logical Structure of a Class Tab. 5 shows the member methods in OJCIass 
handling a logical structure of a class. Using these methods, metaprograms can 
obtain information considering class inheritance and member hiding Although 
these member methods can be implemented by combining the member methods 
m lab.2, they are provided for convenience. We think that providing these meth- 
ods is significant from the viewpoint that class metaobjects represent a logical 
structure of a program. 

Table 5. Member Methods in OJCIass for introspection (2) 



OJCIass Q got Intarf aces () 

Returns all the interfaces implemented by this class or the all the super- 
interfaces of this interface. 

boolean isAssignableFrom (OJCIass clazz) 

Determines if this class/interface is either the same as, or is a superclass 
or superinterface of, the given class/ interface. 

OJMethodQ getMethods (OJCIass situation) 

Returns all the class available from the given situation, including those 

declared and those inherited from superclasses /supermterfaces. 
OJMettjod getJfethod (String name, OJCIass □ types, OJCIass situation) 

Returns the specified method available from the given situation. 
OJMethod get InvokedMetliod (String name, OJCIass □ types, OJCIass situation) 

Returns the method, of the given name, invoked by the given arguments 

types, and available from the given situation. 



In considering the class inheritance mechanism, the member methods de- 
fined in a given class are not only the member methods described in that class 
declaration but also the inherited ones. Thus, method metaobjects obtained by 
invoking getMethodsQ on a class metaobject include the methods explicitly de- 
clared in its class declaration but also the methods inherited from its superclass 
or superinterfaces. 

Moreover, accessibility of class members is restricted in Java by member 
modifiers like public, protected or private. Thus, getMethodsO returns 
only the member methods available from the class specified by the argument. 
For instance, if the specified class is not a subclass or in the same package, 
getMethods () returns only the member methods with public modifier. In Fig. 3, 
since the metaprogram passes this to getMethodsO, it obtains all the member 
methods defined in that class. 

3.4 Type-Driven Translation 

As macro expansion in Open Java is managed by metaobjects corresponding to 
each class (type), this translation is said to be type-driven. In the above example, 
only the member method translateDef initionC) of OJCIass is overridden to 
translate the class declarations of specified classes (callee-side translation). 



In addition to the caUee-side translation, OJClass provides a framework to 
translate the code related to the corresponding class spreaded over whole pro- 
gram selectively (caller-side translation). The parts related to a certain class is, 
for example, instance creation expressions or field access expressions. 

Here, we take up an example of a macro that enables programming with 
the Flyweight[6] pattern to explain this mechanism. This design pattern is 
applied to use objects-sharing to support large numbers of fine-grained objects 
efficiently. An example of macro supporting uses of this pattern would need to 
translate an instance creation expression of a class Glyph: 

nen Glyph('c') 

into a class method call expression: 

GlyphFactory. createCharacter ( ' c ' ) 

The class method createCharacter () returns an object of Glyph correspon- 
dent to the given argument if it was already generated, otherwise it creates a new 
object to return. This way, the program using Glyph objects automatically shares 
an object of Glyph representing a font for a letter c without generating several ob- 
jects for the same letter. In ordinary programming using Glyph objects with the 
Flyweight pattern, programmers must explicitly write createCharacter () in 
their program with creations of Glyph objects. With a support of this macro, 
instance creations can be written in the regular new syntax and the pattern is 
used automatically. 

In OpenJava, this kind of macro expansions are implemented by defining a 
metaclass FlyweightClass to be applied to the class Glyph. This metaclass over- 
rides the member method expandAllocationO of OJClass as in Fig.4. This 
method receives a class instance creation expression and returns a translated 
expression. The system of OpenJava examines the whole source code and apply 
this member method to each Glyph instance creation expression to perform the 
macro expansion. 

Expression expandAllocationClllocationExprossion expr, Environment env) { 
Express ionList args « expr. got Argument s() ; 
return new MethodCall (this, "createCharacter", args); 

> 

Fig. 4. Replacement of class instance expressions 

The member method expandAllocationO receives an AllocationExpression 
object representing a class instance creation expression and an Environment ob- 
ject representing the enviroment of this expression. The Environment object holds 
name binding information such as type of variable in the scope of this expression. 

OpenJava uses type-driven translation to enable the complehensive macro 
expansion of partial code spreaded over various places in program. In macro 
systems for 00 programing languages, it is not only needed to translate a class 



iTn^ bUt trans,atin S expressions using the class togather is also 
needed Jn OpenJava, by denmgam 

grammers can selectively apply macro expansion to the limited expressions re- 
lated to classes controlled by the metaclass. This kind of mechanism has not been 
seen in most of ordinary macro systems except some systems like 0penC++f3] 
Tab. 6 shows the primary member methods of OJCIass which can be overridden 
for macro expansion at caller-side. 

Table 6. Member Methods for Each Place Applied the Macro-Expansion to 

Member method I 



translate!)©* initios () 
expandAUocaticaO 
«xpandArrayAllocat i on () 
©xpandTypoHaoeO 
axpandKethodCall () 
ezpandFieldRead 0 
expandFieldtfriteO 
oxpandCastodExpression ( ) 
oxpandCagtExpression ( ) 



Place applied the macro expansions 
Class declaration " 
Class instance allocation expression 
Array allocation expression 
Class name 

Method class expression 
Field-read expression 
Field-write expression 
Casted expression from this type 
Casted expression to this type 



3.5 Translation Mechanism 

Given a source program, the processor of OpenJava: 

1 Analyzes the source program to generate a class metaobject for each 
class. 

2. Invokes the member methods of class metaobjects to perform macro 
expansion. 

3. Generates the regular Java source program reflecting the modifica- 
tion made by the class metaobjects. 

4. Executes the regular Java compiler to generate the corresponding 
byte code. 

The Order of Translations Those methods of OJCIass whose name start from 
expand performs caller-side translation, and they affect expressions in source 
program declaring another class C. Such expressions may also be translated by 
translateDef initionO of the class metaobject of C as callee-side translation. 
Thus different class metaobjects affect the same part of source program. 

In OpenJava, to resolve this ambiguousness of several macro expansion, 
the system always invokes translateDef initionO first as callee-side transla- 
tion, then it apply caller-side translation to source code of class declarations 
which was already applied callee-side translation. Metaprogrammers can de- 
sign metaprogram considering this specified order of translation. In this rule, 



if translateDef initionO changes an instance creation expression of class X 
mto Y's, expandAllocationO defined in the metaclass of X is not performed. 

Moreover, the OpenJava system always performs translateDef initionO 
for superclasses first, i.e. the system performs it for subclasses after superclasses. 
As a class definition strongly depends on the definition of its superclass, the 
translation of a class often varies depending on the definition of its superclass. 
To settle the definition of superclasses, the system first translates the source 
program declaring superclasses. Additionally, there are some cases where the 
definition of a class D affects the result of translation of a class E. In Open- 
Java, from translateDef initionO for E, metaprogrammer can explicitly spec- 
ify that translateDef initionO for D must be performed before. 

In the case there are dependency relationships of translation among several 
macro expansions, consistent order of translation is specified to address this 
ambiguousness of translation results. 



Dealing with Separate Compilation In Java, classes can be used in program 
only if they exist as source code or byte code (.class file). If there is no source 
code for a class C, the system cannot specifiy the metaclass of C, as is. Then, for 
instance, it cannot perform the appropriate expandAllocationO on instance 
creation expressions of C. 

Therefore, OpenJava automatically preserves metalevel information such as 
the metaclass name for a class when it processes the callee-side translation of each 
class. These preservation are implemented by translating these information into a 
string held in a field of a special class, which is to be compiled into byte code. The 
system uses this byte code to obtain necessary metalevel information in another 
process without source code of that class. Additionally, metaprogrammers can 
request the system to preserve customized metalevel information of a class. 

Metalevel information can be preserved as special attributes of byte code. 
In OpenJava, such information is used only at compile-time but not at runtime. 
Thus, in order to save runtime overhead, we choosed to preserve such information 
in separated byte code which is not to be loaded by JVM at runtime. 



3.6 Syntax Extension 

With OpenJava macros, a metaclass can introduce new class/member modifiers 
and clauses starting with the special word at some limited positions of the regular 
Java grammar. The newly introduced clauses are valid only in the parts related 
to instances of the metaclass. 

In a class declaration (callee-side), the positions allowed to introduce new 
clauses are: 

- before the block of member declarations, 

- before the block of method body in each method declaration, 

- after the field variable in each field declaration. 

And in other class declarations (caller-side), the allowed position is: 



- after the name of the class. 

Thanks to the limited positions of new clauses, the system can parse source 
programs without conflicts of extended grammers. Thus, metaprogrammers do 
not have to care about conflicts between clauses. 

class VectorStack instantiates AdapterClass 
adapts Vector ia v to Stack 

{ 



Fig. 5. An example of syntax extension in OpenJava 

Fig. 5 shows an example source program using a macro, a metaclass Adapter- 
Class, supporting programming with the Adapter pattern[6]. The metaclass in- 
troduces a special clause beginning with adapts to make programmers to write 
special description for the Adapter pattern in the class declaration. The adapts 
clause in the Fig. reffig: VectorStack VectorStack is the adapter to a class Stack 
for a class Vector. The information by this clause is used only when the class 
metaobjects representing VectorStack performs macro expansion. Thus, for other 
class metaobjects, semantical information added by the new clause is recognized 
as a regular Java source code. 

static SyntaxRule getDeclSuffix (String keyword) { 
if (keyword. equals ("adapts")) { 
return new ConpositeftaleC 
new TypeNaaeRuleO, 

new PrepFhraseRuleCin", new IdentifierftuleO) , 
^ new PrepPhraseftale("to" f new TypeHameEtale 0 ) ); 

return null; 

> 



Fig. 6. A meta-program for a customized suffix 

To introduce this adapts clause, metaprogrammers implement a member 
method getDeclSuff ix() in the metaclass AdapterClass as shown in Fig. 6. 
The member method getDeclSuff ix() is invoked by the system when needed, 
and returns a SyntaxRule object representing the syntax grammer begenning 
with the given special word. An instance of the class SyntaxRule implements 
a recursive descendant parser of LL(k), and analyzes a given token series to 
generate an appropriate AST. The system uses SyntaxRule objects obtained by 
invoking getDeclSuff ix() to complete the parsing. 

For metaprogrammers of such SyntaxRule objects, OpenJava provides a class 
library of subclasses of SyntaxRule, such as parsers of regular Java syntax ele- 
ments and synthesizing parser for tying, repeating or selecting other SyntaxRule 



objects. Metaprogrammers can define their desired clauses by using this library 
or by implementing a new subclass of SyntaxRule. ^ 

3.7 Metaclass Model of OpenJava 

A class must be managed by a single metaclass in OpenJava. Though it would 
be useful rf programmers could apply several metaclasses to a class we did not 
implement such a feature because there is a problem of conflict of translation 
between metaclasses. And, a metaclass for a class A does not manage a subclass 
A of A, that is, the metaclass of A does not perform the callee-side and caller- 
side translation of A' it is not specified to be the metaclass of A' in the source 
program declaring A'. 

For innerclasses such as member classes, local classes, anonymous classes in 
the Java language, each of them are also an instance of a metaclass in OpenJava 
lnus programmers may apply a desired metaclass to such classes. 

4 Related Work 

There are a number of systems using the class metaobjects model for represent- 
ing a logical structure of a program: 3-KRS[16], ObjVlispfS], CLOS M0Pfl3] 
SmaUtalk-80[8], and so on. The reflection API[11] of the Java language also uses 
this model although the reflection API does not allow to change class metaob- 
jects; it only allows to inspect them. Furthermore, the reflection API uses class 
metaobjects for making class definition accessible at runtime. On the other hand 
OpenJava uses class metaobjects for macro expansion at compile-time. 

OpenC++[3] also uses the class metaobject model. OpenJava inherits sev- 
eral features, such as the type-driven translation mechanism, from OpenC-f +. 
However, the data structure mainly used in OpenC++ is still an AST (abstract 
syntax tree). MPC++[10] and EPP[9] are similar to OpenC++ with respect to 
the data structure. As mentioned in section 2, an AST is not an appropriate 
abstraction for some macros frequently used in 00 programming. 

5 Conclusion 

This paper describes OpenJava, which is a macro system for Java providing 
a data structure called class metaobjects. A number of research activities have 
been done for enhancing expressive power of macro systems. This research is also 
in this stream. OpenJava is a macro system with a data structure representing 
a logical structure of an 00 program. This made it easier to describe typical 
macros for 00 programming which was difficult to describe with ordinary macro 
systems. 

To show the effectiveness of OpenJava, we implemented some macros in 
OpenJava for supporting programming with design patterns. Although we saw 
that class metaobjects are useful for describing those macros, we also found 



limitations of OpenJava. Since a single design pattern usually contains several 

vTh* u"™ Sy8tem 8h0uld ab,e to deal ^ *ose classes as a single 
entity[17j. However it is not easy for OpenJava to do that because macros Se 
applied to each class. It is future work to address this problem by incorporate 
upenJava with techniques like aspect-oriented programming[12]. 
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Preface 



The Java™ Media Framework (JMF) is an application programming inter- 
face (API) for incorporating time-based media into Java applications and 
applets. This guide is intended for Java programmers who want to incor- 
porate time-based media into their applications and for technology pro- 
viders who are interested in extending JMF and providing JMF plug-ins to 
support additional media types and perform custom processing and ren- 
dering. 



About JMF 

The JMF 1.0 API (the Java Media Player API) enabled programmers to 
develop Java programs that presented time-based media. The JMF 2.0 API 
extends the framework to provide support for capturing and storing 
media data, controlling the type of processing that is performed during 
playback, and performing custom processing on media data streams. In 
addition, JMF 2.0 defines a plug-in API that enables advanced developers 
and technology providers to more easily customize and extend JMF func- 
tionality. 

The following classes and interfaces are new in JMF 2.0: 



AudioFormat 

BufferControl 

CaptureDevi ce 

CI oneabl eDataSou rce 

ConnnectionErrorEvent 

DataSi nkEvent 



BitRateControl 
. BufferToImage 
Captu reDevi ceinf o 
Codec 
DataSi nk 
DataSi nkListener 



Buffer 

BufferTransferHandler 
Captu reDevi ceManage r 
Conf i gu r eCompl eteEvent 
DataSi nkErrorEvent 
Demultiplexer 
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Effect 


EndOfStreamEvent 


Fi 1 eTypeDescri ptor 


Format 


FormatChangeEvent 


FormatControl 


FrameCrabbi ngControl 


FramePositioni ngControl 


FrameProcessi ngControl 


FrameRateControl 


H261Control 


H261Format 


H263Control 


H263Format 


ImageToBuffer 


IndexedCol o r Fo rroat 


InputSourceStream 


KeyFrameControl 


MonitorControl 


MpegAudioControl 


Multiplexer 


NoStorageSpaceErrorEvent 


PacketSizeControl 


Plugln 


PluglnManager 


PortControl 


Processor 


ProcessorModel 


Pul 1 Buff e rDataSou rce 


Pull Buff erStream 


PushBufferOataSource 


PushBufferStream 


QualityControl 


(tenderer 


RCBFormat 


Si 1 enceSuppressi onControl 


St r eamWr i te rCont rol 


Track 


TrackControl 


VideoFormat 


VideoRenderer 


YUVFormat 



In addition, the Medi aPlayer Java Bean has been included with the JMF 
API in j avax . medi a . bean . pi aye rbean. Medi aPl aye r can be instantiated 
directly and used to present one or more media streams. 

Future versions of the JMF API will provide additional functionality and 
enhancements while maintaining compatibility with the current API. 



Design Goals for the JMF API 

JMF 2.0 supports media capture and addresses the needs of application 
developers who want additional control over media processing and ren- 
dering. It also provides a plug-in architecture that provides direct access 
to media data and enables JMF to be more easily customized and 
extended. JMF 2.0 is designed to: 

• Be easy to program 

• Support capturing media data 

• Enable the development of media streaming and conferencing 
applications in Java 
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• Enable advanced developers and technology providers to implement 
custom solutions based on the existing API and easily integrate new 
features with the existing framework 

• Provide access to raw media data 

• Enable the development of custom, downloadable demultiplexers, 
codecs, effects processors, multiplexers, and Tenderers (JMF plug-ins) 

• Maintain compatibility with JMF 1.0 



About the JMF RTP APIs 

The classes in javax. media, rtp, javax. media, rtp. event, and 
javax. media, rtp. rtcp provide support for RTP (Real-Time Transport Pro- 
tocol). RTP enables the transmission and reception of real-time media 
streams across the network. RTP can be used for media-on-demand appli- 
cations as well as interactive services such as Internet telephony. 

JMF-compliant implementations are not required to support the RTP 
APIs in javax. media. rtp, javax. media. rtp. event, and 
javax. media, rtp. rtcp. The reference implementations of JMF provided 
by Sun Microsystems, Inc. and IBM Corporation fully support these APIs. 

The first version of the JMF RTP APIs (referred to as the RTP Session Man- 
ager API) enabled developers to receive RTP streams and play them using 
JMF. In JMF 2.0, the RTP APIs also support the transmission of RTP 
streams. 

The following RTP classes and interfaces are new in JMF 2.0: 

SendStream SendStreamLi stener Inacti veSendStreamEvent 

ActiveSendStreamEvent SendPayl oadChangeEvent NewSendStreamEvent 

ClobalTransmi ssionStats Transmi ssionStats 

The RTP packages have been reorganized and some classes, interfaces, 
and methods have been renamed to make the API easier to use. The pack- 
age reorganization consists of the following changes: 

• The RTP event classes that were in javax. media, rtp. session are now 
in j avax . medi a . rtp . event. 

• The RTCP-related classes that were in javax. media, rtp. session are 
now in javax . medi a . rtp . rtcp. 
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• The rest of the classes in javax . medi a . rtp . sessi on are now in 
javax . medi a . rtp and the javax . medi a . rtp . sessi on package has been 
removed. 

The name changes consist primarily of the removal of the RTP and RTCP 
prefixes from class and interface names and the elimination of non-stan- 
dard abbreviations. For example, RTPRecvStreamListener has been 
renamed to ReceiveStreamListener. For a complete list of the changes 
made to the RTP packages, see the JMF 2.0 Beta release notes. 

In addition, changes were made to the RTP APIs to make them compatible 
with other changes in JMF 2.0: 

• javax. media, rtp. session, ioand 

javax . medi a . rtp . session . depacketi zer have been removed. Custom 
RTP packetizers and depacketizers are now supported through the 
JMF 2.0 plug-in architecture. Existing depacketizers will need to be 
ported to the new plug-in architecture. 

• Buffer is now the basic unit of transfer between the SessionManager 
and other JMF objects, in place of DePacketizedUnit and 
DePacketizedObject. RTP-formatted Buffers have a specific format 
for their data and header objects. 

• BaseEncodi nglnf o has been replaced by the generic JMF Format object. 
An RTP-specific Format is differentiated from other formats by its 
encoding string. Encoding strings for RTP-specific Formats end in 
_RTP. Dynamic payload information can be provided by associating a 
dynamic payload number with a Format object. 

Design Goals for the JMF RTP APIs 

The RTP APIs in JMF 2.0 support the reception and transmission of RTP 
streams and address the needs of application developers who want to use 
RTP to implement media streaming and conferencing applications. These 
APIs are designed to: 

• Enable the development of media streaming and conferencing 
applications in Java 

• Support media data reception and transmission using RTP and RTCP 

• Support custom packetizer and depacketizer plug-ins through the 
JMF 2.0 plug-in architecture. 

• Be easy to program 
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Partners in the Development of the JMF API 

The JMF 2.0 API is being jointly designed by Sun Microsystems, Inc. and 
IBM Corporation. 

The JMF 1.0 API was jointly developed by Sun Microsystems Lie, Intel 
Corporation, and Silicon Graphics, Inc. 

Contact Information 

For the latest information about JMF, visit the Sun Microsystems, Inc. 
website at: 

http://java. sun. com/products/java-media/jmf/ 

Additional information about JMF can be found on the IBM Corporation 
website at: 

http : //www . software . i bm. com/net . medi a/ 
About this Document 

This document describes the architecture and use of the JMF 2.0 API. It 
replaces the Java Media Player Guide distributed in conjunction with the 
JMF 1.0 releases. 

Except where noted, the information in this book is not implementation 
specific. For examples specific to the JMF reference implementation devel- 
oped by Sun Microsystems and IBM corporation, see the sample code and 
solutions available from Sun's JMF website (http ://java. sun . com/prod- 
ucts/j ava-medi a/jmf /i ndex . html ). 



Guide to Contents 

This document is split into two parts: 

• Part 1 describes the features provided by the JMF 2.0 API and 
illustrates how you can use JMF to incorporate time-based media in 
your Java applications and applets. 

• Part 2 describes the support for real-time streaming provided by the 
JMF RTP APIs and illustrates how to send and receive streaming 
media across the network. 
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Part 1 is organized into six chapters: 

• "Working with Time-Based Media"— sets the stage for JMF by 
introducing the key concepts of media content, presentation 
processing, and recording. ' 

• 'TJndeislanding JMF"-introduces the JMF 2.0 API and describes the 
nigh-level architecture of the framework. 

• 7jL CSentinS Time - Based Media with JMF'-describes how to use 
JMF Players and Processors to present time-based media. 

• "Processing Time-Based Media with JMF"— describes how to 
manipulate media data using a JMF Processor. 

• "Capturing Time-Based Media with JMF"— describes how to record 
media data using JMF DataSources and Processors. 

• "Extending JMF"— describes how to enhance JMF functionality by 
creating new processing plug-ins and implementing custom JMF 
classes. 

Part 2 is organized into six chapters: 

• "Working with Real-Time Media Streams"--provides an overview of 
streaming media and the Real-time Transport protocol (RTP). 

• "Understanding the JMF RTP API"-describes the JMF RTP APIs. 

• "Receiving and Presenting RTP Media Streams"— illustrates how to 
handle RTP Client operations. 

• "Transmitting RTP Media Streams"— illustrates how to handle RTP 
Server operations. 

• ''ImportmgandExporrmgRTPMediaStreams"-showshowtoread 
and write RTP data to a file. 

• "Creating Custom Packetizers and Depacketizers"-^describes how 
to use JMF plug-ins to support additional RTP packet formats and 
codecs. 

At the end of this document, you'll find Appendices that contain complete 
sample code for some of the examples used in these chapters and a glos- 
sary of JMF-specific terms. & 
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Change History 

Version JMF 2.0 FCS 

• Fixed references to TrackControl methods to reflect modified 
TrackControl API. 

• Fixed minor sample code errors. 

• Clarified behavior of cloneable data sources. 

• Clarified order of events when writing to a file. 
Version 0.9 

Internal Review Draft 

Version 0.8 

JMF 2.0 Beta draft: 

• Added an introduction to RIP, Working with Real-Time Media 
Streams, and updated the RTP chapters. 

• Updated to reflect API changes since the Early Access release. 

• Added an example of registering a plug-in with the PI uglnManager. 

• Added chapter, figure, table, and example numbers and changed the 
example code style. 

Version 0.7 

JMF 2.0 Early Access Release 1 draft: 

• Updated and expanded RTP chapters in Part 2. 

• Added Demultiplexer example to "Extending JMF". 

• Updated to reflect API changes since the public review. 
Version 0.6 

Internal Review Draft 
Version 0.5 

JMF 2.0 API public review draft. 

• Added new concepts chapter, "Working with Time-Based Media". 

• Reorganized architecture information in "Understanding JMF". 
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• Incorporated RTP Guide as Part 2. 
Version OA 

JMF 2.0 API licensee review draft. 
Comments 

Please submit any comments or suggestions you have for improving this 
document to jmf -comments@eng . sun . com. 



Part 1: 

Java™ Media Framework 



2 

JMF API Guide 



Working with 
Time-Based Media 



Any data that changes meaningfully with respect to time can be character- 
ized as time-based media. Audio clips, MIDI sequences, movie dips, and 
animations are common forms of time-based media. Such media data can 
be obtained from a variety of sources, such as local or network files, cam- 
eras, microphones, and live broadcasts. 

This chapter describes the key characteristics of time-based media and 
describes the use of time-based media in terms of a fundamental data pro- 
cessing model: 





7? < -\^ Receive from 
the network 



Process 

Apply effect fitters 



A <->A Compress or decompress 



A «► B Convert between formats 





Output 

Present 

Save to a file 

Send across 
W the network 



Figure 1-1: Media processing model. 
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Streaming Media 

A key characteristic of time-based media is that it requires timely delivery 
and processing. Once the flow of media data begins, there are strict timing 
deadlines that must be met, both in terms of receiving and presenting the 
data. For this reason, time-based media is often referred to as streaming 
media— it is delivered in a steady stream that must be received and pro- 
cessed within a particular timeframe to produce acceptable results. 

For example, when a movie is played, if the media data cannot be deliv- 
ered quickly enough, there might be odd pauses and delays in playback. 
On the other hand, if the data cannot be received and processed quickly 
enough, the movie might appear jumpy as data is lost or frames are inten- 
tionally dropped in an attempt to maintain the proper playback rate. 

Content Type 

The format in which the media data is stored is referred to as its content 
type. QuickTime, MPEG, and WAV are all examples of content types. Con- 
tent type is essentially synonymous with file type— content type is used 
because media data is often acquired from sources other than local files. 

Media Streams 

A media stream is the media data obtained from a local file, acquired over 
the network, or captured from a camera or microphone. Media streams 
often contain multiple channels of data called tracks. For example, a 
Quicktime file might contain both an audio track and a video track. Media 
streams that contain multiple tracks are often referred to as multiplexed or 
complex media streams. Demultiplexing is the process of extracting individ- 
ual tracks from a complex media stream. 

A track's type identifies the kind of data it contains, such as audio or 
video. The format of a track defines how the data for the track is struc- 
tured. 

A media stream can be identified by its location and the protocol used to 
access it. For example, a URL might be used to describe the location of a 
QuickTime file on a local or remote system. If the file is local, it can be 
accessed through the FILE protocol. On the other hand, if if s on a web 
server, the file can be accessed through the HTTP protocol. A media locator 
provides a way to identify the location of a media stream when a URL 
can't be used. 
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Media streams can be categorized according to how the data is delivered: 

• P^at^amferisimtiatedandcontroUedfromtheclientside For 
example, Hypertext Transfer Protocol (HTTP) and FILE are pull ' 
protocols. y 

• Push-toe server initiates data transfer and controls the flow of data 
For example, Real-time Transport Protocol (RTP) is a push protocol " 
used for streaming media. Similarly, the SGI MediaBa* protocol is a 
push protocol used for video-on-demand (VOD). 

Common Media Formats 

The following tables identify some of the characteristics of common media 
formats. When selecting a format, if s important to take into account the 
characteristics of the format, the target environment, and the expectations 
of the intended audience. For example, if you're delivering media content 
via the web, you need to pay special attention to the bandwidth require- 
ments. * 

The CPU Requirements column characterizes the processing power neces- 
sary for optimal presentation of the specified format. The Bandwidth 
Requirements column characterizes the transmission speeds necessary to 
send or receive data quickly enough for optimal presentation. 



Format 


Content Type 


Quality 


CPU 
Requirements 


Bandwidth 
Requirements 


Cinepak 


AVI 

QuickTime 


Medium 


Low 


High 


MPEG-1 


MPEG 


High 


High 


High 


H.261 


AVI 
RTP 


Low 


Medium 


Medium 


H.263 


QuickTime 

AVI 

RTP 


Medium 


Medium 


Low 


JPEG 


QuickTime 
AVI 


High 


High 


High 



RTP 
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Format 


Content Type Quality 


CPU 
Requirements 


Bandwidth 
Requirements 


Indeo 


QuickTime Medium 
AVI 


Medium 


Medium 


Table 1-1: Common video formats. 






Format 


Content Type Quality 


CPU 
Requirements 


Bandwidth 
Requirements 


PCM 


AVI High 

QuickTime 

WAV 


Low 


High 


Mu-Law 


AVI Low 
QuickTime 


Low 


High 



ADPCM 

(DVL 

EMA4) 



MPEG-1 

MPEG 
Layer3 

GSM 
G.723.1 



WAV 
RTP 

AVI 

QuickTime 

WAV 

RTP 

MPEG 

MPEG 



WAV 
RTP 

WAV 
RTP 



Medium Medium 



Medium 



High 
High 



High 
High 



Low Low 
Medium Medium 



High 

Medium 

Low 
Low 



Table 1-2: Common audio formats. 



fn 0 ^ 0r S a t are with particular applications and requirements 

in mind. High-quality, high-bandwidth formats are generally targeted 
toward CD-ROM or local storage applications. H.261 and H.263 are gener- 
ally used for video conferencing applications and are optimized for video 
where there's not a lot of action. Similarly G.723 is typically used to pro- 
duce low bit-rate speech for telephony applications. 



Working with Time-Based Media 

Media Presentation 



Most tune-based media is audio or video data that can be presented 
trough output devices such as speakers and monitors Su"«s are 
the most common destination for media data output. Media strSmTcaT 
alsobesenttoomerdes^ 

ted across the network. An output destination for media data iTso^ 
times referred to as a data sink. me 

Presentation Controls 

While a media stream is being presented, VCR-style presentation contrnk 
are often provided to enable the user to control playK^e? 
controlpane for a movie player might offer buttL for stopp^ 
fast-forwarding, and rewinding the movie. &=»«rung, 



Latency 



t^LZ^'JT 1 ^^ When P resentin S a ^dia stream that resides 
on me network, the presentation of the media stream cannot begin imme- 

Zl ** as a delay between the time that 

they click the start button and the time when playback actually starts. 

Multimedia presentations often combine several types of time-based 
™Jf£ t0 , a sy^onized presentation. For example, background music 
might be played during an image slide-show, or animated text might be 
synchronized with an audio or video clip. When the presentation of multi- 
ple media streams is synchronized, it is essential to take into account the 
start latency of each stream-otherwise the playback of the different 
streams might actually begin at different times. 

Presentation Quality 

The quality of the presentation of a media stream depends on several fac- 
tors, mcluding: 

• The compression scheme used 

• The processing capability of the playback system 

• The bandwidth available (for media streams acquired over the 
network) 
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Media Processing 

1. If the stream is multiplexed, the individual tracks are extracted 

2. If the individual tracks are compressed they are decoded. 

3. If necessary, the tracks are converted to a different format. 

4. Effect filters are applied to the decoded tracks (if desired). 

The tracks are then delivered to the appropriate output device If the 
media stream is to be stored instead of rendered to an outoTdevke the 
processing stages might differ slightly. For example, if you wanteTto «L 
t^audio and video fxom a video camera, p^te^EEZZZ 

1. The audio and video tracks would be captured. 

2. Effect filters would be applied to the raw tracks (if desired). 

3. The individual tracks would be encoded. 

4 ' ^ re r nPreSSed WOUld * multi P lexed ^ a single media 

5. The multiplexed media stream would then be saved to a file. 
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Demultiplexers and Multiplexers 

A demultiplexer extracts individual tracks of media data from » ™ i« 



Codecs 



A codec performs media-data compression and decompression Wh™ 

att'tr^- — ^ to « —P—d ZSeS^- 

?"™^ whe * it is decoded it is converted to a non-com 
pressed (raw) format suitable for presentation. 

Each codec has certain input formats that it can handle and certain o„nw 
formats that it can generate. In some situations, a ^SooSSSffiS 
used to convert from one format to another. nesotcodec s nught be 

Effect FHters 

^SF^V* d T ified "l"* 61 P^P-^tag effects or post-process 
^effects, dependmg on whether they are applied before ofafter *T 



Renderers 



A renderer is an abstraction of a presentation device. For audio, the pre- 

SZT ITS 18 ^ 7 ** C ° mpUter/S Wdware audio ^dtolt- 
puts sound to the speakers. For video, the presentation device is typicX 
the computer monitor. yy^y^uxy 

Compositing 

Certain specialized devices support compositing. Compositing time-based 
media is the process of combining multiple tracks of data onto a single 
presentation medium. For example, overlaying text on a video presenta- 
^lu ne f 0mm ° n £ 2 m ° f com P° si tog. Compositing can be done in 

A ^ ** V** 0 ™ ^positing can be 
abstracted as a renderer that can receive multiple tracks of input data. 
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Media Capture 

^ thought of as the .^fphase of * ^££££g* 

^rrr^ 

captured and manipulated separately o^ST.?T ""^ * 
Plexed stream thatLtams b5h m^S^^^tt^ 

Capture Devices 

To capture ttae-based media you need speciaUzed hardware-for exam 
pie, to capture audio from a live source, you need a m i™^T J 

tan. and an appropriate video capture card. Most systeS SET. 
query mecharusm to find out what capture devices are avauablT 

Capture devices can be characterized as either push or pull sources For 
example, a stall camera is a pull source-the user contJs wh^^Ze 

p^rai3&^ h ^* eK ---— ^ 

The format of a captured media stream depends on the processing per- 
formed by the capture device. Some devices do very littfe proceSand 
dehver raw, uncompressed data. Other capture devices m££25£ft£ 
data in a compressed format. me 

Capture Controls 

process. For example, a capture control panel might enable the user to 
speafy the data rate and encoding type for the captured stream a^Sart 
and stop the capture process. »«iasrart 



Understanding JMF 



Java™ Media Framework (JMF) provides a unified architecture and m~ 
time-based media data. JMF is designed to support most standi ™Zi 



te S^SSSSSJ p r 8CS f j3Va Platform ' ^ deli ™ the prom- 
«*of WnteCtoce^un Anywhere™'' to devel operswh o want to use 
media such as audio and video in their Java programs. JMF pJSte a 
common cross-platform Java API for accessing uliderlymg JLSSL- 
^•JMFimplemen^^ 

rng operating system, while developers can easily create portable Java 
programs that feature time-based media by writing to the JMF API. 

With JMF, you can easily create applets and applications that present, cap- 
ture, manipulate, and store time-based media. The framework enables 
advanced developers and technology providers to perform custom pro- 
cessing of raw media data and seamlessly extend JMF to support addi- 
tional content types and formats, optimize handling of supported formats 
and create new presentation mechanisms. formats, 

High-Level Architecture 

Devices such as tape decks and VCRs provide a familiar model for record- 
ing, processing, and presenting time-based media. When you play a movie 
using a VCR, you provide the media stream to the VCR by insertine a 
video tape. The VCR reads and interprets the data on the tape and sends 
appropriate signals to your television and speakers. 



u 
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Video camera 

(Capture Device) 




Video tape 

(Data Source) 



VCR 

(Player) 




Output Devices 

<^^pn^^ p ^ gStt ^^ (Destination) 

JMF uses this same basic model. Ad*, source encapsulates the media 
stream much like a video tape and a player provided proo^3L, 

witn jMf requires the appropriate input and output devices such a* 
microphones, cameras, speakers, and monitors. 

SSL!? W Sf ^ Playeis ^ integral P 31 * 8 of JMF's high-level API for 
managing the capture, presentation, and processing of time-based media 

a so provides a lower-level API that supports L seamles^te^a 
tan of custom processing components and extensions. Tto layerir^L- 
vides Java developers with an easy-to-use API for incorporating^/ 
exSlS ] Z B , Pr0gramS ^ mamtai -ng the^xibilirV^d 

10 SUPP ° rt 3dVanCed ^ 2d future 
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Time Model 

keeps toe to nanosecond precision. A particular point in time is rro- 
specification of time m nanoseconds. 

Classes that support the JMF time model implement CI ock to keep track of 
bme for a particular media stream. The Clock interface derWth b*Sc 

Sonoffi 



Clock 



syncStart 
stop 

getMediaTime 

setMediaTime 

getRate 

setRate 

getStopTime 

setStopTime 

getTimeBase 

setTimeBase 



has a 



TimeBase 



getTime 

getNanoseconds 



Time 



TimeClong nanoseconds] 
TimeCdouble seconds) 
getNanoseconds 
getSeconds 

secondsToNanoseconds 



Figure 2-3: JMF time model 



Duration 



getDuration 



AG ock uses a Ti me Base to keep track of the passage of time while a media 
stream is being presented. A TimeBase provides a constantly ticking toe 
source much like a crystal oscillator in a watch. The only information that 
a Ti meBase provides is its current time, which is referred to as the time-base 
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To keep track of the current media time, a CI ock uses: 
' p^t^ 

• The media start-time-the position in the media stream where 
presentation begins. 

• The playback rate-how fast the Clock is running in relation to its 

example, a rate of 1.0 represents the normal playback rate for the 
media stream, while a rate of 2.0 indicates that L presentation will 
run at twice me normal rate. A negative rate indicates that the Goc^ is 
running in the opposite direction from its TimeBase-for example a 
negative rate might be used to play a media stream backward 

When presentation begins, the media time is mapped to the time-base 
time and die advancement of the time-base time is used to measure the 
passage of time. During presentation, the current media time is calculated 
using the following formula: ^uiaiea 

MediaTime = MediaStartTime + RateCTimeBaseTime - TimeBaseStartTime) 

When the presentation stops, the media time stops, but the time-base time 
continues to advance. If the presentation is restarted, the media time is 
remapped to the current time-base time. 

Managers 

The JMF API consists mainly of interfaces that define the behavior and 
interaction of objects used to capture, process, and present time-based 
media. Implementations of these interfaces operate within the structure of 
the framework. By using intermediary objects called managers, JMF makes 
it easy to integrate new implementations of key interfaces that can be used 
seamlessly with existing classes. 
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JMF uses four managers: 

• Manager-handles the construction of PI ayers, Processors 
DataSources and DataSinks. This level of Liirection Sows new 

^rspecnve these objects are always created the same way whether 

Data^nks ^ PrOCessors ' ^Sources, and 

# ^f evic ^ ana 9 er - m ^tains a registry of available capture 

• PI uglnManager-maintains a registry of available JMF plug-in 
processmg components, such as Multiplexers, Demultiplexers 
Codecs, Effects, and Renderers. 

mpA^r^T b3 ? d ° n y ° U ' U nCed to USe Manager create 
methods to construct the PI ayers, Processors, DataSources and DataSi nk, 

you 11 use the CaptureDeviceManager to find out what devices are artUbfe 
and access information about them. If you're interested ^oXS 
what processing is performed on the data, you might also query the PI uo- 
InManager to determine what plug-ins have been registered. 

If you extend JMF functionality by implementing a new plug-in, you can 
register it with the PI uglnManager to make it avaLble to ProLso ™th* 
support the plug-in API. To use a custom PI ayer, Processor^a^ 
ZS^^ ™' ^ ^ **** paCka ^ prefix with the 

Event Model 

JMF uses a stmrtured event reporting mechanism to keep JMF-based pro- 
grams informed of the current state of the media system and enable JMF- 
based programs to respond to media-driven error conditions, such as out- 
of data and resource unavailable conditions. Whenever a JMF object needs 
to report on the current conditions, it posts a Medi aEvent. Medi aEvent fc 

lowlh^lw r^ ^ PartiCUlar ° f events - ^ ob i e <*> fol- 
low the established Java Beans patterns for events. 
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For each type ofJMF object that can post Medi aEvents TA/TF Hofi 
sponding listener interface. To receive JStoSZ^^ ' ^ 
posted, you implement the appropriate listened ZZffJl a 6nt 18 



MediaEvent 



Controller 



addControllerLi stener 
removeControl 1 erLi stener 



has a 



LontroHerLi stener 



extends 



control lerUpdateCControT lerEvent)! 



creates 



Control lerEvent 



getSourceCbntrol ler 



Figure 2-4: JMF event model. 



"3£>T ° n "t nager ° b ' ects 3180 P° st events - For more information, 
RTF Events" on page 122. 



see 



Data Model 



JMF media players usually use DataSources to manage the transfer of 
media-content. A DataSource encapsulates both the location of media and 
the protocol and software used to deliver the media. Once obtained the 
source cannot be reused to deliver other media. 

A DataSource is identified by either a JMF Medi aLocator or a URL (univer- 
sal resource locator). A Medi aLocator is similar to a URL and can be con- 
structed from a URL, but can be constructed even if the corresponding 

* n0t inStaUed ° n me (In ' ava ' a URL can only be 

constructed if the corresponding protocol handler is installed on the svs- 
tern.) J 

A DataSource manages a set of SourceStream objects. A standard data 
source uses a byte array as the unit of transfer. A buffer data source uses a 
Buffer object as its unit of transfer. JMF defines several types of Data- 
Source objects: 
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I Controls | j Duration I 

I DataSource I m anages one or more, i 

" n SourceStream J 



Figure 2-5: JMF data model. 



- j Pull DataSource | 



juRLDataSource ~] 
- |PunBufferDataSource| 
- jpushDataSource | 
■ J PushBufferDataSource] 



Pu1TtourceStream| 
j InputSou rceStream j 



PullBufferStreaml 
PushSourceStream J 
PushBufferStreamj 
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Push and Pull Data Sources 

wnrtfilf f^T* fr ° m 3 Variet y ° f aoma ^ such a * local or net- 

work files and live broadcasts. JMF data sources can be categorized 

according to how data transfer is initiated: 

• Pull Data-Source-ihe client initiates the data transfer and controls the 

flow of data from pull data-sources. Established protocols for this type 

of data include Hypertext Transfer Protocol (HTTP) and FILE IMF 

defines two types of pull data sources: Pul 1 DataSource and 

Pull Buff erDataSource, which uses a Buffer object as its unit of 
transfer. 

• Pwh Data-Source-lhe server initiates the data transfer and controls 
the flow of data from a push data-source. Push data-sources include 
broadcast media, multicast media, and video-on-demand (VOD) For 
mS>V CaSt dat3/ ° ne P rotoco1 » Real-time Transport Protocol 
mnX ^ de x r /! Ve i 0pment by Ae lhtanel Sneering Task Force 
(IETFJ^^eMediaBaseprotocol developed by SGIis one protocol used 
for VOD. JMF defines two types of push data sources: PushDataSource 
and PushBuff erDataSource, which uses a Buffer object as its unit of 
transfer. 

The degree of control that a client program can extend to the user depends 
on the type of data source being presented. For example, an MPEG file can 



Specialty DataSources 

^ a r^ % data ~ ** ~ 

Adoneable data source can be used to create clones of either a pull or 
push DataSource. To create a cloneable DataSource you call the C„,n» 

rr C1 ?r ableDataS0UrCe mCth0d - d P- s - SKSS you want 
to clone. Once a DataSource has been passed to created oneableData 

Source you should only interact with the cloneable DataSourc a^d its 
clones; the original DataSource should no longer be used directly 

Qoneable data sources implement the Sou reed on eable interface, which 
defines one method, createdone. By calling createdone, you can raate 
anynumber of donesofthe DataSource that was used to cons^hf 
cloneable DataSource. The clones can be controlled through the doneable 
DataSource used to create them- when connect, di sconnfet, start or 
^ti?^ source, themethodcallsarepropa- 

The clones don't necessarily have the same properties as the cloneable 

HnlT^ t0 ° r ^Source. For example a 

cloneable data source created for a capture device might function as a 
master data source for its clones-in this case, unless the cloneable data 
source is used, the clones won't produce any data. If you hook up both the 
cloneable data source and one or more clones, the clones will produce 
data at the same rate as the master. 

A MergingDataSource can be used to combine the SourceStreams from sev- 
eral DataSources into a single DataSource. This enables a set of Data- 
Sources to be managed from a single point of control-when connect 
di sconnect, start, or stop is called on the MergingDataSource, the method 
calls are propagated to the merged DataSources. 

To construct a MergingDataSource, you call the Manager createMerging- 
DataSource method and pass in an array that contains the data sources 
you want to merge. To be merged, all of the DataSources must be of the 
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Data Formats 

The exact media format of an object is represented by a Format obiect Thp 
JMF extends Format to define audio- and video-specific formats. 



Format 



Audi oForroat [ 



VideoForroat 

3 



FormatControl 



getFormat 
setFormat 

getSupportedFormats 

isEnabled 

set Enabled 



IndexedCol or Format J 
RCBFormat [ 



YUVFormat 



J 



JPECFormat 



1 H261Format | 

"H263Format | 



] 



Figure 2-6: JMF media formats. 

An AudioFormat describes the attributes specific to an audio format, such 
as samp e rate, bits per sample, and number of channels. A vi deoFormat 
encapsulates information relevant to video data . Several formats are 
derived from VideoFormat to describe the attributes of common video 
formats, including: 

• IndexedCol or Format 

• RCBFormat 

• YUVFormat 

• JPECFormat 

• H2 61 Format 

• H263Format 
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To receive notification of format changes from a Control 1 er, you imple- 
ment the ControllerListener interface and listen for FormatChangeEvents 
(For more information, see "Responding to Media Events" on page 54.) 

Controls 

JMF Control provides a mechanism for setting^and querying attributes of 
an object. A Control often provides access to a corresponding user inter- 
face component that enables user control over an object's attributes. Many 
JMF objects expose Controls, including Controller objects, DataSource 
objects, DataSi nk objects, and JMF plug-ins. 

Any JMF object that wants to provide access to its corresponding Control 
objects can implement the Controls interface. Controls defines methods 
for retrieving associated Control objects. DataSource and PI ugln use the 
Controls interface to provide access to their Control objects. 

Standard Controls 

JMF defines the standard Control interfaces shown in Figure 2-8- "TMF 
controls." 5 ' J 

CachingControl enables download progress to be monitored and dis- 
played. If a Player or Processor can report its download progress it 
implements this interface so that a progress bar can be displayed to the 

user* 

CainControl enables audio volume adjustments such as setting the level 
and muting the output of a PI ayer or Processor. It also supports a listener 
mechanism for volume changes. 



MediaEvent 



CainControl 



addCai nChanqeLi stener 
removeCai nChangeLi stener 



has one or more 

GainChangeLi stener 



gai nChange(Cai nChangeEvent) 



extends 



creates 



Figure 2-7: Gain control. 



£a1 nChangeEvent 



getDB 

getLevel 

getMute 
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j~ Control j 



-|BitRateControl | 
- jBufferControl | 
-[CachingControl "[ 



-[ FormatControl 




- | FrameRateControT | 
- jcainControl "| 
- jH263Contro1 | 
-|H261Contro1 | 
-| KeyFrameControl | 
- ^MonitorControl | 



-[MpegAudioControl "| 

- j PacketSi zeCont rol | 

- j PortControl j 

- jQualityControl | 

- |RTPContro1 | 

- | SilenceSuppressionControT] 

- j StreamWriterControl j 



Figure 2-8: JMF controls. 

DataSink or Multiplexer objects that read media from a DataSource and 
write it out to a destination such as a file can implement the StreamWri t- 
erControl interface. This Control enables the user to limit the size of the 
stream that is created. 



FramePositioningControl and FrameGrabbingControl export frame-based 
capabilities for Players and Processors. FramePositioningControl enables 
precise frame positioning within a Player or Processor object's media 
stream. FrameGrabbingControl provides a mechanism for grabbing a still 
video frame from the video stream. The FrameCrabbi ngControl can also be 
supported at the Renderer level. 
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Objecte that have a Format can implement the FormatControl interface to 
provide access to the Format. FormatControl also provides methods for 
querying and setting the format. P aes metnods for 

L T ^°,r r01 i J at yP eof FormatControl that provides the mechanism 
for confroUing what processing a Processor object performs on a pil- 
lar track of media data. With the TrackControl methods, you can sperifr 
what format conversions are performed on individual tracks and select 
the Effect, Codec, or Renderer plug-ins that are used by the Processor 
(For more information about processing media data, see "Processing * 
Time-Based Media with JMF" on page 71.) 5 

Two controls, PortControl and MonitorControl enable user control over 
the capture process. PortControl defines methods for controlling the out- 
put of a capture device. MonitorControl enables media data to be pre- 
viewed as it is captured or encoded. 

ticular' objert 1 U8er " tevd COntrol OVer me buff ering done by a par- 

JMF also defines several codec controls to enable control over hardware or 
software encoders and decoders: 

• Bi tRateControl— used to export the bit rate information for an 
incoming stream or to control the encoding bit rate. Enables 
specification of the bit rate in bits per second. 

• FrameProcessi ngControl— enables the specification of frame 
processing parameters that allow the codec to perform minimal 
processing when it is falling behind on processing the incoming data. 

• FrameRateControl— enables modification of the frame rate. 

• H261Control—enables control over the H.261 video codec still-image 
transmission mode. 

• H263Control— enables control over the H.263 video-codec parameters 
including support for the unrestricted vector, arithmetic coding, 
advanced prediction, PB Frames, and error compensation extensions. 

• KeyFrameControl— enables the specification of the desired interval 
between key frames. (The encoder can override the specified key- 
frame interval if necessary.) 

• MpegAudioControl— exports an MPEG audio codec's capabilities and 
enables the specification of selected MPEG encoding parameters. 

• Qual i tyControl —enables specification of a preference in the trade-off 
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b^een, quality and CPU usage in the processing performed by a 
codec Thus quality hint can have different effects depending on the 
type of compression. A higher quality setting will result in tetter 
quahty of the resulting bits, for example better image quality for 

SilenceSuppressionControl-enables specification of silence 
suppression parameters for audio codecs. When silence suppression 
mode is on, an audio encoder does not output any data if it detects 
silence at its input. 
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User Interface Components 

A Control can provide access to a user interface Component that exposes its 
control behavior to the end user. To get the default user interface compo- 
nent for a particular Control, you call getControl Component. This method 
returns an AWT Component that you can add to your applet's presentation 
space or application window. 

A Control 1 er might also provide access to user interface Components For 
example, a PI ayer provides access to both a visual component and a con- 
trol panel component— to retrieve these components, you call the PI ayer 
methods getVi sua! Component and getControl Panel Component. 

If you don't want to use the default control components provided by a 
particular implementation, you can implement your own and use the 
event listener mechanism to determine when they need to be updated For 
example, you might implement your own GUI components that support 
user interaction with a Player. Actions on your GUI components would 
trigger calls to the appropriate Player methods, such as start and stop 
By registering your custom GUI components as Control 1 erLi steners for 
the PI ayer, you can also update your GUI in response to changes in the 
Player object's state. 



Extensibility 

Advanced developers and technology providers can extend JMF function- 
ality in two ways: 

• By implementing custom processing components (plug-ins) that can be 
interchanged with the standard processing components used by a JMF 
Processor 
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• By directly implementing the Controller, Player, Processor 
DataSource, or DataSi nk interfaces 

hnplementing a JMF plug-in enables you to customize or extend the caoa 
bihties o a Processor without having to implement one from scratch ? 
Once a plug-m is registered with JMF, it can be selected as a processing 

teusTd to: 3 " 7 Pr ° CeSSOr ** SUPP ° rtS * e plUS " in M ^ Wins L 

• Extend or replace a Processor object's processing capability piecewise 
by selecting the individual plug-ins to be used. mtv piecewise 

• Access the media data at specific points in the data flow. For example 
different Effect plug-ins can be used for pre- and post-processing of 
the media data associated with a Processor. 

• Process media data outside of a PI ayer or Processor. For example, you 
mightusea Demultiplexer plug-in to get individual audio tracks from 
anruUhplexed media-stream so you could play the tracks through Java 

In situations where an even greater degree of flexibility and control is 
required, custom implementations of the JMF Controller, Player Proces- 
sor DataSource, or DataSi nk interfaces can be developed and used seam- 
lessly with existing implementations. For example, if you have a 
hardware MPEG decoder, you might want to implement a PI ayer that 
takes input from a DataSource and uses the decoder to perform the pars- 
ing, decoding, and rendering all in one step. Custom Players and Proces- 
sors can also be implemented to integrate media engines such as 
Microsoft* s Media Player, Real Network's RealPlayer, and IBM's HotMe- 
dia with JMF. 

Note: JMF Pl ayers and Processors are not required to support plug-ins 
P ug-ins won't work with JMF 1.0-based PI ayers and some Processor im- 
plementafaonsmight choose not to support them. The reference imple- 
mentation of JMF 2.0 provided by Sun Microsystems, Inc. and IBM 
Corporation fully supports the plug-in API. 

Presentation 

In JMF, the presentation process is modeled by the Control! er interface 
Controller defines the basic state and control mechanism for an object 
that controls, presents, or captures time-based media. It defines the phases 
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that a media. controller goes through and provides a mechanism for con- 
trolling the transitions between those phases. A number of the operations 
that must be performed before media data can be presented can be time 
consuming, so JMF allows programmatic control over when they occur. 

A Controller posts a variety of controller-specific MediaEvents to provide 
notification of changes in its status. To receive events from a Controller 
such as a Player, you implement the Control! erListener interface For 
more information about the events posted by a Control 1 er, see "Control- 
ler Events on page 30. 

The JMF API defines two types of Control 1 ers: PI ayer s and Processors A 
** er or Pro «ssor is constructed for a particular data source and is nor- 
mally not re-used to present other media data. 
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has a 



TimeBase 



Duration 



extends 



Controller 



MediaHandler 



^ Afxtends /\fi 
Player 



extends 
has a 



3 



extends 



DataSource 



Processor 



Figure 2-9: JMF controllers. 



Players 

A PI ayer processes an input stream of media data and renders it at a pre- 
cise time. A DataSource is used to deliver the input media-stream to the 
PI ayer.The rendering destination depends on the type of media beine pre- 
sented. ° r 




Figure 2-10: JMF player model. 
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A PI ayer does not provide any control over the processing that it performs 
or how it renders the media data. F«rorms 

PI ayer supports standardized user control and relaxes some of the opera- 
tional restrictions imposed by dock and Controller. 

has a 



Clock 



syncStart 
stop 

getMediaTime 
getTimeBase 
setTimeBase 
setRate 



TimeBase 



Duration 



getDuration 



extends 



Controller 



extends 



prefetch 
realize 
deallocate 
close 

addCont rol 1 e rLi stene r 
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setSource 



Player 
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Figure 2-11: JMF players. 
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setSource 
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getVi sua! Component 
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Player States 

A PI ayer can be in one of six states. The CI ock interface defines the two 
primary states: Stopped and Started. To facilitate resource management, 
Control 1 er breaks the Stopped state down into five standby states- Unreal- 
ized, Realizing, Realized, Prefetching, and Prefetched. 



Stopped Started 

realize ' 




Transition Events: 

RCE RealtzeCompleteEvent 

PFCE PrefetehComplsteEvent 

SE StopEvent 

Figure 2-12: Player states. 
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• A PI ayer in the Unrealized state has been instantiated, but does not vet 
know anything about its media. When a media PI ayer is first created 
it is Unrealized. 

• Whenrealize is called, a PI ayer moves from the Unrealized state into 
the Realizing state. A Realizing PI ayer is in the process of determinine 
its resource requirements. During realization, a PI ayer acquires the 
resources that it only needs to acquire once. These might include 
rendering resources other than exclusive-use resources. (Exclusive- 
use resources are limited resources such as particular hardware 
devices that can only be used by one PI ayer at a time; such resources 
are acquired during Prefetching.) A Realizing Player often downloads 
assets over the network. 

• When a PI ayer finishes Realizing, it moves into the Realized state A 
Realized PI ayer knows what resources it needs and information about 
the type of media itis to present. Because a Realized Player knows how 
to render its data, it can provide visual components and controls. Its 
connections to other objects in the system are in place, but it does not 
own any resources that would prevent another Player from starting. 

• When prefetch is called, a PI ayer moves from the Realized state into 
the Prefetching state. A Prefetching PI ayer is preparing to present its 
media. During this phase, the PI ayer preloads its media data, obtains 
exclusive-use resources, and does whatever else it needs to do to 
prepare itself to play. Prefetching might have to recur if a PI ayer 
objecf s media presentation is repositioned, or if a change in the PI ayer 
object's rate requires that additional buffers be acquired or alternate 
processing take place. 

• When a PI ayer finishes Prefetching, it moves into the Prefetched state. A 
Prefetched PI ayer is ready to be started. 

• Calling start puts a PI ayer into the Started state. A Started PI ayer 
object's time-base time and media time are mapped and its clock is 
running, though the Player might be waiting for a particular time to 
begin presenting its media data. 

A PI ayer posts Transi tionEvents as it moves from one state to another. 
The Control 1 erLi stener interface provides a way for your program to 
determine what state a Player is in and to respond appropriately. For 
example, when your program calls an asynchronous method on a PI ayer 
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or Processor, it needs to listen for the appropriate event to determine 
when the operation is complete. 

Using this event reporting mechanism, you can manage a PI ayer object's 
start latency by controlling when it begins Realizing and Prefetching. It also 
enables you to determine whether or not the PI ayer is in an appropriate 
state before calling methods on the PI ayer. 

Methods Available in Each Player State 

To prevent race conditions, not all methods can be called on a PI ayer in 
every state. The following table identifies the restrictions imposed by JMF. 
If you call a method that is illegal in a PI ayer object's current state, the 
PI ayer throws an error or exception. 



Method 


Unrealized 


Real 17 pd 




started 




Player 


Player 


Player 


Player 


addCont roll er 


NotRealizedError 


legal 


legal 


Cl ockStartedError 


deallocate 


legal 


legal 


legal 


ClockStartedError 


getCont rol Panel Component 


NotRealizedError 


legal 


legal 


legal 


getCainControl 


NotRealizedError 


legal 


legal 


legal 


getStart Latency 


NotRealizedError 


legal 


legal 


legal 


getTimeBase 


NotReal i zedEr ror 


legal 


legal 


legal 


getVi sualComponent 


NotRealizedError 


legal 


legal 


legal 


mapToTiffleBase 


CI ockS topped Excepti on 


CI ockStoppedExcepti on 


ClockStoppedExcepti on 


legal 


removeControll er 


NotRealizedError 


legal 


legal 


ClockStartedError 


setMediaTime 


NotRealizedError 


legal 


legal 


legal 


setRate 


NotRealizedError 


legal 


legal 


legal 


setStopTime 


NotRealizedError 


legal 


legal 


StopTimeSetError 
if previously set 


setTimeBase 


NotRealizedError 


legal 


legal 


Cl ockStartedError 


syncStart 


NotPrefetchedError 


NotPrefetchedError 


legal 


Cl ockStartedError 



Table 2-1: Method restrictions for players. 
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Processors 

Processors can also be used to present media data. A Processor is just a 
specialized type of PI ayer that provides control over what processing is 
performed on the input media stream. A Processor supports all of the 
same presentation controls as a PI ayer. 




Figure 2-13: JMF processor model. 

In addition to rendering media data to presentation devices, a Processor 
can output media data through a DataSource so that it can be presented by 
another Player or Processor, further manipulated by another Processor, 
or delivered to some other destination, such as a file. 

For more information about Processors, see "Processing" on page 32. 
Presentation Controls 

Li addition to the standard presentation controls defined by Control 1 er, a 
PI ayer or Processor might also provide a way to adjust the playback vol- 
ume. If so, you can retrieve its Gai nCont rol by calling getCai nControl . A 
GainControl object posts a Gai nChangeEvent whenever the gain is modi- 
fied. By implementing the Gai nChangeLi stener interface, you can respond 
to gain changes. For example, you might want to update a custom gain 
control Component. 

Additional custom Control types might be supported by a particular 
Player or Processor implementation to provide other control behaviors 
and expose custom user interface components. You access these controls 
through the getControls method. 

For example, the CachingControl interface extends Control to provide a 
mechanism for displaying a download progress bar. If a PI ayer can report 
its download progress, it implements this interface. To find out if a PI ayer 
supports CachingControl, you can call getControl (Cachi ngControl) or 
use getControl s to get a list of all the supported Control s. 
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Standard User Interface Components 

You can also implement custom user interface components, and use the 
event teener mechanism to determine when they need to upSed! 

Controller Events 

Ue f C ?r? 1 i erEVentS P ° Sted by 3 Control ^r such as a Player or Proces- 
"tiofev^s Cate8 ° rieS: notifications ' dosed events, and tran- 

• Change notification events such as RateChangeEvent 
DurationUpdateEven^and FormatChangeEvent indicate that some 
attribute of the Con t roll e r has changed, often in response to a method 
call. For example, a Player posts a RateChangeEvent when its rate is 
changed by a call to setRate. 

• Transi tionEvents allow your program to respond to changes in a 
Controller object's state. A Player posts transition events whenever 
it moves from one state to another. (See "Player States" on page 26 for 
more information about the states and transitions.) 

• ControllerClosedEventsarepostedbyaControllerwhenitshuts 
down. When a Controller posts a Controlled! osedEvent, it is no 
longer usable. A ControllerErrorEvent is a special case of 
ControllerClosedEvent. You can listen for ControllerErrorEvents so 
that your program can respond to Controller malfunctions to 
minimize the impact on the user. 
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Figure 2-14: JMF events. 
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Processing 

u^finpH 18 3 PlayeP * DataSource ™ ^Put performs some 

user-defined processing on the media data, and then outputs the pro- 
cessed media data. v 



p1 ayer 


has a i * 

► uatabource 


start 
setSource 
addController 
getVi sual Component 
getCont rol Panel Component 
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getDataOutput 



creates a, 



DataSource 



Figure 2-15: JMF processors. 

A Processor can send the output data to a presentation device or to a 
DataSource. If the data is sent to a DataSource, that DataSource can be used 
as the input to another PI ayer or Processor, or as the input to a DataSi nk. 

While the processing performed by a PI ayer is predefined by the imple- 
mentor, a Processor allows the application developer to define the tvpe of 
processing that is applied to the media data. This enables the application 
of effects, mixing, and compositing in real-time. 

The processing of the media data is split into several stages: 

r 




Processor 



Figure 2-16: Processor stages. 



• Demultiplexing is the process of parsing the input stream. If the 
stream contains multiple tracks, they are extracted and output 
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separately. For example, a QuickTime file might be demultiplexed 
into separate audio and video tracks. Demultiplexing is performed 
automatically whenever the input stream contains multiplexed data. 

• Pre-Processing is the process of applying effect algorithms to the 
tracks extracted from the input stream. 

• Transccdmgistneprocessofconvertingeachtrackofmediadatafrom 
one input format to another. When a data stream is converted from a 
compressed type to an uncompressed type, it is generally referred to 
as decoding. Conversely, converting from an uncompressed type to a 
compressed type is referred to as encoding. 

• Post-Processing is the process of applying effect algorithms to 
decoded tracks. 

• Multiplexing is the process of interleaving the transcoded media 
tracks into a single output stream. For example, separate audio and 
video tracks might be multiplexed into a single MPEG-1 data stream 
You can specify the data type of the output stream with the Processor 
setOutputContentDescri ptor method. 

• Rendering is the process of presenting the media to the user. 

The processing at each stage is performed by a separate processing com- 
ponent. These processing components are JMF plug-ins. If the Processor 
supports TrackControl s, you can select which plug-ins you want to use to 
process a particular track. There are five types of JMF plug-ins: 

• Demultiplexer— parses media streams such as WAV, MPEG or 
QuickTime. If the stream is multiplexed, the separate tracks are 
extracted. 

• Effect— performs special effects processing on a track of media data. 

• Codec— performs data encoding and decoding. 

• Mul ti pi exe r— combines multiple tracks of input data into a single 
interleaved output stream and delivers the resulting stream as an 
output DataSource. 

• Renderer— processes the media data in a track and delivers it to a 
destination such as a screen or speaker. 



Processor States 

A Processor has two additional standby states, Configuring and Config- 
ured, which occur before the Processor enters the Realizing state.. 
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realize 




deallocate 

Transition Events: 
CCE ConfigureCompleteEvent 
RCE RealizeCompteteEvent 
PFCE PrefetchCompleteEvent 
SE StopEvent 

Figure 2-17: Processor states. 

• A Processor enters the Configuring state when configure is called. 
While the Processor is in the Configuring state, it connects to the 
DataSource, demultiplexes the input stream, and accesses information 
about the format of the input data. 

• The Processor moves into the Configured state when it is connected to 
the DataSource and data format has been determined. When the 
Processor reaches the Configured state, a ConfigureCompleteEvent is 
posted. 

• When Realize is called, the Processor is transitioned to the Realized 
state. Once the Processor is Realized it is fully constructed. 

While a Processor is in the Configured state, getTrackControls can be 
called to get the TrackControl objects for the individual tracks in the 
media stream. These TrackControl objects enable you specify the media 
processing operations that you want the Processor to perform. 

Calling realize directly on an Unrealized Processor automatically transi- 
tions it through the Configuring and Configured states to the Realized state 
When you do this, you cannot configure the processing options through 
the TrackControl s — the default Processor settings are used. 

Calls to the TrackControl methods once the Processor is in the Realized 
state will typically fail, though some Processor implementations might 
support them. 
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Methods Available in Each Processor State 

Since a Processor is a type of Player, the restrictions on when methods can 
be called on a PI ayer also apply to Processors. Some of the Processor-spe- 
cific methods also are restricted to particular states. The following table 
shows the restrictions that apply to a Processor. If you call a method that 
is illegal m the current state, the Processor throws an error or exception 
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Method 


Unrealized 
Processor 


Configuring 
Processor 


Configured 
Processor 


Realized 
Processor 


ad dCont roller 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


deallocate 


legal 


legal 


legal 


legal 


getControlPanelComponent 


NotRealizedError 


NotReal i zedError 


notKea i i zeofcrror 


legal 


getControls 


legal 


legal 


legal 


legal 


getDataOutput 


NotRealizedError 


NotRealizedError 


NotReal i zedError 


legal 


getGainControl 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


getOutputContentDescri ptor 


NotConfi gu red Error 


NotConfi gu redError 


legal 


legal 


getStart Latency 


NfJt'RpAl i 70(tFrmr 


NotReal i zedError 


NotRealizedError 


legal 


Descriptors 


legal 


legal 


legal 


legal 


getTimeBase 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


getTrackControls 


NotConfi gu red Error 


NotConfi gu redError 


legal 


FormatChange- 
Exception 


getVi sualComponent 


Not Real i zedEr ror 


nuinea i iZcucrrur 


NotReal i zedError 


legal 


mapToTimeBase 


ClockStoppedExcepti on 


CI ockStoppedExcepti on 


ClockStoppedException 


CI ockStopped- 
Excepti on 


realize 


legal 


legal 


legal 


legal 


removeCont roller 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


se tOutpu tContentDesc ri ptor 


NotConfi gu red E rror 


NotConfi gu red Error 


legal 


FormatChange- 
Exception 


setMediaTime 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


setRate 


NotReal i zedError 


NotRealizedError 


NotRealizedError 


legal 


setStopTime 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


setTimeBase 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


syncStart 


Not Prefetched Error 


NotPrefetchedError 


NotPrefetchedError 


NotPrefetchedError 



Table 2-2: Method restrictions for processors. 
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Processing Controls 

You can control what processing operations the Processor performs on a 
track through the TrackControl for that track. You call Processor^ 
S^a^ ^allofthetracksin 

Through a TrackControl, you can explicitly select the Effect, Codec, and 
Renderer pug-ins you want to use for the track. To find out what options 

Z ^taltd 5 ' ^ W *" P1 U9lnMan39er t0 ° Ut What pC 

To control the transcoding thaf s performed on a track by a particular 
Codec, you can get the Control s associated with the track by calling the 
TrackControl getControl s method. This method returns the codec con- 
trols available for the track, such as BitRateControl and QualityControl 
(for more information about the codec controls defined by JMF see "Con 
trols" on page 20.) J ' 

If you know the output data format that you want, you can use the set- 
Format method to specify the Format and let the Processor choose an 
appropriate codec and renderer. Alternatively, you can specify the output 
format when the Processor is created by using a Processor-Model A Pro- 
cessorModel defines the input and output requirements for a Processor 
When a ProcessorModel is passed to the appropriate Manager create 
method, the Manager does its best to create a Processor that meets the 
specified requirements. 



Data Output 

The getDataOutput method returns a Processor object's output as a Data- 
Source. This DataSource can be used as the input to another Player or Pro- 
cessor or as the input to a data sink. (For more information about data 
sinks, see "Media Data Storage and Transmission" on page 37.) 

A Processor objecf s output DataSource can be of any type: PushData- 
Source, PushBufferDataSource, Pull DataSource, or Pull Buff erDataSource. 

Not all Processor objects output data— a Processor can render the pro- 
cessed data instead of outputting the data to a DataSource. A Processor 
that renders the media data is essentially a configurable PI ayer. 
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Capture 

A multimedia capturing device can act as a source for multimedia data 
de ivery. For example, a microphone can capture raw audio input or a die- 
ital video capture board might deliver digital video from a camera. Such 
capture devices are abstracted as DataSources. For example, a device that 
provides timely delivery of data can be represented as a PushDataSource 
Any type of DataSource can be used as a capture DataSource: PushData- 
Source, PushBufferDataSource, Pull DataSource, or Pull Buff erDataSource. 

Some devices deliver multiple data streams— for example, an audio/ 
video conferencing board might deliver both an audio and a video stream 
The corresponding DataSource can contain multiple SourceStreams that 
map to the data streams provided by the device. 



Media Data Storage and Transmission 

A DataSi nk is used to read media data from a DataSource and render the 
media to some destination— generally a destination other than a presenta- 
tion device. A particular DataSi nk might write data to a file, write data 
across the network, or function as an RTP broadcaster. (For more informa- 
tion about using a DataSi nk as an RTP broadcaster, see "Transmitting RTP 
Data With a Data Sink" on page 149.) 

Like PI ayers, DataSi nk objects are constructed through the Manager using 
a DataSource. A DataSi nk can use a StreamWri terControl to provide addi- 
tional control over how data is written to a file. See "Writing Media Data 
to a File" on page 74 for more information about how DataSi nk objects are 
used. 



Storage Controls 

A DataSi nk posts a DataSi nkEvent to report on its status. A DataSi nkEvent 
can be posted with a reason code, or the DataSi nk can post one of the fol- 
lowing DataSi nkEvent subtypes: 

• DataSi nkErrorEvent, which indicates that an error occurred while the 
DataSi nk was writing data. 

• EndOf StrearaEvent, which indicates that the entire stream has 
successfully been written. 
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To respond to events posted by a DataSi nk, you implement the DataSi n- 
kL i s te ne r interface. 

Extensibility 

You can extend JMF by implementing custom plug-ins, media handlers, 
and data sources. 

Implementing Plug-Ins 

By implementing one of the JMF plug-in interfaces, you can directly access 
and manipulate the media data associated with a Processor: 

• Implementing the Demul ti plexer interface enables you to control how 
individual tracks are extracted from a multiplexed media stream. 

• Implementing the Codec interface enables you to perform the 
processing required to decode compressed media data, convert media 
data from one format to another, and encode raw media data into a 
compressed format. 

• Implementing the Effect interface enables you to perform custom 
processing on the media data. 

• Implementing the Mul t i pi exe r interface enables you to specify how 
individual tracks are combined to form a single interleaved output 
stream for a Processor. 

• Implementing the Renderer interface enables you to control how data 
is processed and rendered to an output device. 

Note: The JMF Plug-In API is part of the official JMF API, but JMF PI ayers 
and Processors are not required to support plug-ins. Plug-ins won't work 
with JMF 1.0-based Players and some Processor implementations might 
choose not to support them. The reference implementation of JMF 2.0 pro- 
vided by Sun Microsystems, Inc. and IBM Corporation fully supports the 
plug-in API. 7 YV 

Custom Codec, Effect, and Renderer plug-ins are available to a Processor 
through the TrackControl interface. To make a plug-in available to a 
default Processor or a Processor created with a ProcessprModel, you need 
to register it with the PI uglnManager. Once you've registered your plug-in, 
it is included in the list of plug-ins returned by the PI uglnManager get- 
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PI uglnLi st method and can be accessed by the Manage r when it constructs 
a Processor object. 



Implementing MediaHandlers and DataSources 

If the JMF Plug-In API doesn't provide the degree of flexibility that you 
need, you can directly implement several of the key JMF interfaces: Con- 
trol! er, Player, Processor, DataSource, and DataSink. For example you 
might want to implement a high-performance PI ayer that is optimized to 
present a single media format or a Control 1 er that manages a completely 
different type of time-based media. 

The Manager mechanism used to construct Player, Processor, DataSource, 
and DataSi nk objects enables custom implementations of these JMF inter- 
faces to be used seamlessly with JMF. When one of the create methods is 
called, the Manager uses a well-defined mechanism to locate and construct 
the requested object. Your custom class can be selected and constructed 
through this mechanism once you register a unique package prefix with 
the PackageManager and put your class in the appropriate place in the pre- 
defined package hierarchy. 



MediaHandler Construction 

Players, Processors, and DataSi nks are all types of MediaHandlers — they 
all read data from a DataSource. A Medi aHandl er is always constructed for 
a particular DataSource, which can be either identified explicitly or with a 
MediaLocator. When one of the createMediaHandTer methods is called, 
Manager uses the content-type name obtained from the DataSource to find 
and create an appropriate MediaHandler object. 
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Figure 2-18: JMF media handlers. 

JMF also supports another type of Medi aHandl er, Medi aProxy. A Medi aProxy 
processes content from one DataSource to create another. Typically, a Medi - 
aProxy reads a text configuration file that contains all of the information 
needed to make a connection to a server and obtain media data. To create 
a Player from a Medi aProxy, Manager: 

1. Constructs a DataSource for the protocol described by the Medi aLocator 

2. Uses the content-type of the DataSource to construct a Medi aProxy to 
read the configuration file. 

3. Gets a new DataSource from the Medi aProxy. 

4. Uses the content-type of the new DataSource to construct a PI ayer. 



The mechanism that Manager uses to locate and instantiate an appropriate 
Medi aHandl er for a particular DataSou rce is basically the same for all types 
of Medi aHandl ers: 
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• Using the list of installed content package-prefixes retrieved from 
PackageManager , Manager generates a search list of available 
MediaHandler classes. 

• Manager steps through each class in the search list until it finds a class 
named Hand! er that can be constructed and to which it can attach the 
DataSource. 

When constructing Players and Processors, Manager generates the search 
list of available handler classes from the list of installed content package- 
prefixes and the content-type name of the DataSource. To search for Play- 
ers, Manager looks for classes of the form: 

<content package-prefix>. media. content. <content-type>. Handler 

To search for Processors, Manager looks for classes of the form: 

<content package-prefix> .media. processor . <content-type>. Handl er 

If the located Medi aHandl er is a Medi aProxy, Manager gets a new DataSource 
from the MediaProxy and repeats the search process. 

If no appropriate MediaHandler can be found, the search process is 
repeated, substituting unknown for the content-type name. The unknown 
content type is supported by generic PI ayers that are capable of handling 
a large variety of media types, often in a platform-dependent way. 

Because a DataSi nk renders the data it reads from its DataSource to an out- 
put destination, when a DataSi nk is created the destination must also be 
taken into account. When constructing DataSi nks, Manager uses the list of 
content package-prefixes and the protocol from the Medi aLocator that 
identifies the destination. For each content package-prefix, Manager adds 
to the search list a class name of the form: 

<content package-prefix>. media. datasink. protocol .Handler 

If the located Medi aHandl er is a DataSi nk, Manager instantiates it, sets its 
DataSource and Medi aLocator, and returns the resulting DataSi nk object. If 
the handler is a DataSi nkProxy, Manager retrieves the content type of the 
proxy and generates a list of DataSi nk classes that support the protocol of 
the destination Medi alocator and the content type returned by the proxy: 

<content package-prefix>. media. datasink. protocol .<content-type>. Handler 

The process continues until an appropriate DataSi nk is located or the Man- 
ager has iterated through all of the content package-prefixes. 
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DataSource Construction 

Manager uses the same mechanism to construct DataSources that it uses to 
construct Medi aHandl ers, except that it generates the search list of Data- 
Sou rce class names from the list of installed protocol package-prefixes. 

For each protocol package-prefix, Manager adds to the search list a class 
name of the form: 



protocol package-prefix>. media! protocol .<protocol>.DataSou 



rce 



Manager steps through each class in the list until it finds a DataSource that 
it can instantiate and to which it can attach the MediaLocator. 
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Presenting Time-Based 
Media with JMF 



To present time-based media such as audio or video with JMF, you use a 
PI ayer. Playback can be controlled programmatically or you can display a 
control-panel component that enables the user to control playback interac- 
tively. If you have several media streams that you want to play you need 
to use a separate PI ayer for each one. to play them in sync, you can use 
one of the PI ayer objects to control the operation of the others. 

A Processor is a special type of Player that can provide control over how 
the media data is processed before it is presented. Whether you're using a 
basic PI ayer or a more advanced Processor to present media content, you 
use the same methods to manage playback. For information about how to 
control what processing is performed by a Processor, see "Processing 
Time-Based Media with JMF" on page 71. 

The Medi aPl ayer bean is a Java Bean that encapsulates a JMF player to pro- 
vide an easy way to present media from an applet or application. The 
Medi aPl ayer bean automatically constructs a new Player when a different 
media stream is selected, which makes it easier to play a series of media 
clips or allow the user to select which media clip to play. For information 
about using the Medi aPl ayer bean, see "Presenting Media with the Media- 
Player Bean" on page 66 



Controlling a Player 

To play a media stream, you need to construct a PI ayer for the stream, con- 
figure the PI ayer and prepare it to run, and then start the PI ayer to begin 
playback. 
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Creating a Player 

You create a Player indirectly through the media Manager. To display the 
PI ayer, you get the PI ayer object's components and add them to your 
applet's presentation space or application window. 

When you need to create a new Player, you request it from the Manager by 
calling createPl ayer or createProcessor. The Manager uses the media URL 
or Medi aLocator that you specify to create an appropriate PI ayer. A URL 
can only be successfully constructed if the appropriate corresponding URL- 
StreamHandler is installed. Medi aLocator doesn't have this restriction. 

Blocking Until a Player is Realized 

Many of the methods that can be called on a PI ayer require the PI ayer to 
be in the Realized state. One way to guarantee that a PI ayer is Realized 
when you call these methods is to use the Manager createRealizedPlayer 
method to construct the PI ayer. This method provides a convenient way 
to create and realize a PI ayer in a single step. When this method is called, 
it blocks until the PI ayer is Realized. Manager provides an equivalent cre- 
ateRealizeProcessor method for constructing a Realized Processor. 

Note: Be aware that blocking until a PI ayer or Processor is Realized can 
produce unsatisfactory results. For example, if createReal i zedPl ayer is 
called in an applet, Appl et .start and Appl et . stop will not be able to 
interrupt the construction process. 

Using a ProcessorModel to Create a Processor 

A Processor can also be created using a ProcessorModel. The Processor- 
Model defines the input and output requirements for the Processor and the 
Manager does its best to create a Processor that meets these requirements. 
To create a Processor using a ProcessorModel, you call the Manager . cre- 
ateReal izedProcessor method. Example 3-1 creates a Realized Processor 
that can produce IMA4-encoded stereo audio tracks with a 44.1 kHz sam- 
ple rate and a 16-bit sample size. 

Example 3-1: Constructing a Processor with a ProcessorModel. 
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Since the ProcessorModel does not specify a source URL in this example 
Manager implicitly finds a capture device that can capture audio and then 
creates a Processor that can encode that into IMA4. 

Note mat when you create a Realized Processor with a ProcessorModel you 
will not be able to specify processing options through the Processor 
objecf s TrackControl s. For more information about specifying processing 
options for a Processor, see "Processing Time-Based Media with JMF" on 
page 71. 
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Displaying Media Interface Components 

A PI ayer generally has two types of user interface components, a visual 
component and a control-panel component. Some Player implementa- 
tions can display additional components, such as volume controls and 
download-progress bars. 



Displaying a Visual Component 

A visual component is where a PI ayer presents the visual representation 
of its media, if it has one. Even an audio PI ayer might have a visual com- 
ponent, such as a waveform display or animated character. 

To display a Player object's visual component, you: 

1. Get the component by calling getVi sual Component. 

2. Add it to me applef s presentation space or application window. 



You can access the PI ayer object's display properties, such as its x and y 
coordinates, through its visual component. The layout of the Player com- 
ponents is controlled through the AWT layout manager. 



Displaying a Control Panel Component 

A PI ayer often has a control panel that allows the user to control the 
media presentation. For example, a PI ayer might be associated with a set 
of buttons to start, stop, and pause the media stream, and with a slider 
control to adjust the volume. 
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Every Player provides a default control panel. To display the default con- 
trol panel: 

1. Call getControl Panel Component to get the Component. 

2. Add the returned Component to your applet's presentation space or ap- 
plication window. 

If you prefer to define a custom user-interface, you can implement custom 
GUI Components and call the appropriate Player methods in response to 
user actions. If you register the custom components as ControllerLi sten- 
ers, you can also update them when the state of the PI ayer changes. 

Displaying a Gain-Control Component 

PI ayer implementations that support audio gain adjustments implement 
the Cai nControl interface. Cai nControl provides methods for adjusting the 
audio volume, such as setLevel and setMute. To display a Gai nControl 
Component if the PI ayer provides one, you: 

1. Call getCai nControl to get the Cai nControl from the Player. If the 
PI ayer returns null, it does not support the Cai nControl interface. 

2. Call getControl Component on the returned Cai nControl. 

3. Add the returned Component to your applet's presentation space or ap- 
plication window. 

Note that getControl s does not return a Player object's Cai nControl. You 
can only access the Cai nControl by calling getCai nControl . 

Displaying Custom Control Components 

Many PI ayers have other properties that can be managed by the user. For 
example, a video PI ayer might allow the user to adjust brightness and 
contrast, which are not managed through the PI ayer interface. You can 
find out what custom controls a PI ayer supports by calling the getCon- 
trol s method. 



For example, you can call getControl s to determine if a PI ayer supports 
theCachingControl interface. 
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Example 3-2: Using getControl s to find out what Controls are supported. 




Displaying a Download-Progress Component 

The CachingControl interface is a special type of Control implemented by 
PI ayers that can report their download progress. A Cachi ngControl pro- 
vides a default progress-bar component that is automatically updated as 
the download progresses. To use the default progress bar in an applet: 

1. Implement the Control 1 erLi stener interface and listen for 
Cachi ngControl Events in controllerUpdate. 

2. The first time you receive a CachingControl Event: 

a. Call getCachi ngControl on the event to get the caching control. 

b. Call getProgressBar on the CachingControl to get the default 
progress bar component. 

c. Add the progress bar component to your applet's presentation 

space. 

3. Each time you receive a Cachi ngControl Event, check to see if the down- 
load is complete. When getContentProgress returns the same value as 
getContentLength, remove the progress bar. 

The PI ayer posts a Cachi ngControl Event whenever the progress bar needs 
to be updated. If you implement your own progress bar component, you 
can listen for this event and update the download progress whenever 
Cachi ngControl Event is posted. 

Setting the Playback Rate 

The PI ayer objecf s rate determines how media time changes with respect 
to time-base time; it defines how many units a PI ayer object's media time 
advances for every unit of time-base time. The PI ayer object's rate can be 
thought of as a temporal scale factor. For example, a rate of 2.0 indicates 
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that media time passes twice as fast as the time-base time when the PI aver 
is started. r 

In theory, a PI ayer object's rate could be set to any real number, with neg- 
ative rates interpreted as playing the media in reverse. However, some 
media formats have dependencies between frames that make it impossi- 
ble or impractical to play them in reverse or at non-standard rates. 

To set the rate, you call setRate and pass in the temporal scale factor as a 
float value. When setRate is called, the method returns the rate that is 
actually set, even if it has not changed. PI ayers are only guaranteed to 
support a rate of 1.0. 



Setting the Start Position 

Setting a PI ayer object's media time is equivalent to setting a read posi- 
tion within a media stream. For a media data source such as a file, the 
media time is bounded; the maximum media time is defined by the end of 
the media stream. 

To set the media time you call setMedi aTi me and pass in a Ti me object that 
represents the time you want to set. 



Frame Positioning 

Some PI ayers allow you to seek to a particular frame of a video. This 
enables you to easily set the start position to the beginning of particular 
frame without having to specify the exact media time that corresponds to 
that position. Players that support frame positioning implement the 
FramePosi ti oni ngCont rol . 

To set the frame position, you call the FramePosi tioni ngControl seek 
method. When you seek to a frame, the PI ayer object's media time is set 
to the value that corresponds to the beginning of that frame and a Media- 
TimeSetEvent is posted. 

Some PI ayers can convert between media times and frame positions. You 
can use the FramePosi tioni ngControl mapFrameToTime and mapTimeToFrame 
methods to access this information, if if s available. (PI ayers that support 
FramePosi tioni ngControl are not required to export this information.) 
Note that there is not a one-to-one correspondence between media times 
and frames —a frame has a duration, so several different media times 
might map to the same frame. (See "Getting the Media Time" on page 53 
for more information.) 
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Preparing to Start 

Most media Players cannot be started instantly. Before the Player can 
start, certain hardware and software conditions must be met. For example, 
if the Player has never been started, it might be necessary to allocate buff- 
ers in memory to store the media data. Or, if the media data resides on a 
network device, the PI ayer might have to establish a network connection 
before it can download the data. Even if the PI ayer has been started 
before, the buffers might contain data that is not valid for the current 
media position. 



Realizing and Prefetching a Player 

JMF breaks the process of preparing a Player to start into two phases, 
Realizing and Prefetching. Realizing and Prefetching a PI ayer before you start 
it minimizes the time it takes the PI ayer to begin presenting media when 
start is called and helps create a highly-responsive interactive experience 
for the user. Implementing the Cont rol 1 erLi stener interface allows you to 
control when these operations occur. 

Note: Processor introduces a third phase to the preparation process called 
Configuring. During this phase, Processor options can be selected to con- 
trol how the Processor manipulates the media data. For more informa- 
tion, see "Selecting Track Processing Options" on page 72. 

You call realize to move the Player into the Realizing state and begin the 
realization process. You call prefetch to move the PI ayer into the Prefetch- 
ing state and initiate the prefetching process. The real i ze and prefetch 
methods are asynchronous and return immediately. When the PI ayer 
completes the requested operation, it posts a Real i zeCompl eteEvent or 
PrefetchCompleteEvent. "Player States" on page 26 describes the opera- 
tions that a PI ayer performs in each of these states. 

A Player in the Prefetched state is prepared to start and its start-up latency 
cannot be further reduced. However, setting the media time through set- 
MediaTime might return the Player to the Realized state and increase its 
start-up latency. 

Keep in mind that a Prefetched PI ayer ties up system resources. Because 
some resources, such as sound cards, might only be usable by one pro- 
gram at a time, having a PI ayer in the Prefetched state might prevent other 
Players from starting. 
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Determining the Start Latency 

To determine how much time is required to start a PI ayer, you can call 
getStartLatency. For Players that have a variable start latency, the return 
value of getStartLatency represents the maximum possible start latency. 
For some media types, getStartLatency might return UTENCYJJNKNOWN. 

The start-up latency reported by getStartLatency might differ depending 
on the Player object's current state. For example, after a prefetch opera 
tion, the value returned by getStartLatency is typically smaller. A Con- 
trol! er that can be added to a PI ayer will return a useful value once it is 
Prefetched. (For more information, see "Using a Player to Synchronize 
Controllers" on page 57.) 



Starting and Stopping the Presentation 

The Clock and Player interfaces define the methods for starting and stop- 
ping presentation. 



Starting the Presentation 

You typically start the presentation of media data by calling start. The 
start method tells the PI ayer to begin presenting media data as soon as 
possible. If necessary, start prepares the PI ayer to start by performing the 
realize and prefetch operations. If start is called on a Started PI ayer, the 
only effect is that a StartEvent is posted in acknowledgment of the 
method call. 

Clock defines a syncStart method that can be used for synchronization. 
See "Synchronizing Multiple Media Streams" on page 56 for more infor- 
mation. 

To start a Pi ayer at a specific point in a media stream: 

1. Specify the point in the media stream at which you want to start by call- 
ing setMediaTime. 

2. Call start on the Player. 
Stopping the Presentation 

There are four situations in which the presentation will stop: 
• When the stop method is called 
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• When the specified stop time is reached 

• When there's no more media data to present 
t^enmemediadataisbeingreceivedtooslowlyforacceptaH^ 

When a PI ayer is stopped, its media time is frozen if the source of the 

When a Stopped?! ayer is restarted, if the media time was frozen, presenta- 
tion resumes from the stop time. If media time could not be frozen Xn 

t J ^Zf St ° P ? ed ' reCepti ° n ° f me stream ^umes and playback 
begins with the newly-received data. "P«ynacx 

Is1££ pi 3 " 6 " T^J' y ° U ?" *" St ° P method - K y° u caU s to P on 
it™ \*f I** 7 iS ** 3 St °P B y^questEvent is posted in 

acknowledgment of the method call. y 

Stopping the Presentation at a Specified Time 

You can call setStopTime to indicate when a Player should stop The 
Player stops when its media time passes the specified stop time. If the 
Player objecf s rate is positive, the Player stops when the media time 
becomes greater than or equal to the stop time. If the PI ayer object's rate 
is negative, the Player stops when the media time becomes less than or 
equal to the stop time. The Player stops immediately if its current media 
time is already beyond the specified stop time. 

For example, assume that a PI ayer object's media time is 5.0 and setStop- 
Ti me is called to set the stop time to 6.0. If the PI ayer object's rate is posi- 
tive, media time is increasing and the PI ayer will stop when the media 
time becomes greater than or equal to 6.0. However, if the Player object's 
rate is negative, it is playing in reverse and the Player will stop immedi- 
ately because the media time is already beyond the stop time. (For more 
information about PI ayer rates, see "Setting the Playback Rate" on 
page 47.) 

You can always call setStopTime on a Stopped PI ayer. However, you can 
only set the stop time on a Started PI ayer if the stop time is not currently 
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set. If the Started Player already has a stop time, setStopTime throws an 
error. 

You can call getStopTime to get the currently scheduled stop time. If the 
clock has no scheduled stop time, getStopTime returns Clock. RESET. To 
remove the stop time so that the Player continues until it reaches end-of- 
media, call setStopTi me (Clock. RESET). 



Releasing Player Resources 

The deal locate method tells a PI ayer to release any exclusive resources 
and minimize its use of non-exclusive resources. Although buffering and 
memory management requirements for Players are not specified, most 
PI ayers allocate buffers that are large by the standards of Java objects. A 
well-implemented Player releases as much internal memory as possible 
when deal locate is called. 

The deal locate method can only be called on a Stopped PI ayer. To avoid 
ClockStartedErrors, you should call stop before you call deallocate. 
Calling deallocate on a PI ayer in the Prefetching or Prefetched state returns 
it to the Realized state. If deal 1 ocate is called while the PI ayer is realizing, 
the Player posts a DeallocateEvent and returns to the Unrealized state. 
(Once a PI ayer has been realized, it can never return to the Unrealized 
state.) 

You generally call deal 1 ocate when the Pi ayer is not being used. For 
example, an applet should call deal locate as part of its stop method. By 
calling deall ocate, the program can maintain references to the PI ayer, 
while freeing other resources for use by the system as a whole. (JMF does 
not prevent a Realized PI ayer that has formerly been Prefetched or Started 
from maintaining information that would allow it to be started up more 
quickly in the future.) 

When you are finished with a PI ayer (or any other Control 1 er) and are 
not going to use it anymore, you should call close. The close method 
indicates that the Control 1 er will no longer be used and can shut itself 
down. Calling close releases all of the resources that the Controller was 
using and causes it to cease all activity When a Control 1 er is closed, it 
posts a Control 1 erCl osedEvent. A closed Control 1 er cannot be reopened 
and invoking methods on a closed Control 1 er might generate errors. 
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Getting the Time-Base Time 

You ran get a Player object's current time-base time by getting the PI aver 
object's TimeBase and calling getTime: 8 mngtnepiayer 

myCurrentTBTime = playerl.getTimeBaseO .getTimeO ; 

When a PI ayer is running, you can get the time-base time that corre- 
sponds to a particular media time by calling mapToTimeBase. 



Getting the Duration of the Media Stream 

Since programs often need to know how long a particular media stream 
wiU run, all Controllers implement the Duration interface. This interface 
defines a single method, getDuration. The duration represents the length 
of time that a media object would run, if played at the default rate of 1.0. A 
media stream's duration is only accessible through a PI ayer. 

If the duration can't be determined when getDuration is called 
DURATTON_UNKNOWN is returned. This can happen if the PI ayer has not yet 
reached a state where the duration of the media source is available. At a 
later time, the duration might be available and a call to getDuration 
would return the duration value. If the media source does not have a 
defined duration, as in the case of a live broadcast, getDuration returns 
DURATION_UNBOUNDED. 



Responding to Media Events 

Control 1 erLi stener is an asynchronous interface for handling events gen- 
erated by Controller objects. Using the Cont roll erLi stener interface 
enables you to manage the timing of potentially time-consuming PI ayer 
operations such as prefetching. 

Implementing the ControIIerListener Interface 

To implement the Control 1 erLi stener interface, you need to: 

1. Implement the Contrail erLi stener interface in a class. 

2. Register that class as a listener by calling addControl 1 erLi stene r on the 
Cont roll e r that you want to receive events from. 
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When a Control 1 er posts an event, it calls control 1 erUpdate on each 
tered listener. 



regis- 



Typically, cont roll erUpdate is implemented as a series of if-else state- 
ments. 



Example 3-3Jmplementing control! erUpdate. 




This filters out the events that you are not interested in. If you have regis- 
tered as a listener with multiple Controllers, you also need to determine 
which Controller posted the event. ControllerEvents come "stamped" 
with a reference to their source that you can access by calling getSource. 

When you receive events from a Control 1 er, you might need to do some 
additional processing to ensure that the Control 1 er is in the proper state 
before calling a control method. For example, before calling any of the 
methods that are restricted to Stopped PI ayers, you should check the 
Player objecf s target state by calling getTargetState. If start has been 
called, the Player is considered to be in the Started state, though it might 
be posting transition events as it prepares the Player to present media. 

Some types of Cont roll erEvents contain additional state information. For 
example, the StartEvent and StopEvent classes each define a method that 
allows you to retrieve the media time at which the event occurred. 

Using ControllerAdapter 

Cont rol 1 erAdapter is a convenience class that implements Cont rol 1 erLi s- 
tener and can be easily extended to respond to particular Events. To 
implement the Cont roll erLi stener interface using ControllerAdapter, 
you need to: 

1. Subclass ControllerAdapter and override the event methods for the 
events that you're interested in. 

2. Register your Control 1 erAdapte r class as a listener for a particular Con- 
trol! er by calling addControllerLi stener. 
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When a Controller posts an event it calls control! erUpdate on each regis- 
tered listener. ControllerAdapter automatically dispatches the event to 
the appropriate event method, filtering out the events that you're not 
interested in. J 

For example, the following code extends a Control 1 erAdapter with a JDK 
1.1 anonymous inner-class to create a self-contained Player that is auto- 
matically reset to the beginning of the media and deallocated when the 
Player reaches the end of the media. 




If you register a single ControllerAdapter as a listener for multiple Play- 
ers, in your event method implementations you need to determine which 
PI ayer generated the event. You can call getSource to determine where a 
Control! erEvent originated. 



Synchronizing Multiple Media Streams 

To synchronize the playback of multiple media streams, you can synchro- 
nize the Players by associating them with the same TimeBase. To do this, 
you use the getTimeBase and setTimeBase methods defined by the Clock 
interface. For example, you could synchronize pi ayer 1 with pi ayer2 by 
setting pi ayerl to use pi ayer2 * s time base: 

playerl. setTimeBase(player2.getTimeBaseO) ; 

When you synchronize PI ayers by associating them with the same Ti me- 
Base, you must still manage the control of each PI ayer individually. 
Because managing synchronized Players in this way can be complicated, 
JMF provides a mechanism that allows a PI ayer to assume control over 
any other Control 1 er. The Pi ayer manages the states of these Cont rol 1 ers 
automatically, allowing you to interact with the entire group through a 
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single point of control. For more information, see See "Using a Player to 
Synchronize Controllers". sawyer to 
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Using a Player to Synchronize Controllers 

Synchronizing Players directly using syncStart requires that you care- 
fuUy manage the states of all of the synchronized Players. You must con- 
trol each one mdividually listening for events and calling control methods 
on them as appropriate. Even with only a few PI ayers, mis quickly 
becomes a difficult task. Through the PI ayer interface, JMF provides a 
simpler solution: a Player can be used to manage the operation of any 
Controller. J 

When you interact with a managing Player, your instructions are auto- 
matically passed along to the managed Controllers as appropriate The 
managing PI aye r takes care of the state management and synchronization 
for all of the other Controllers. 

This mechanism is implemented through the addController and remove- 
Controller methods. When you call addController on a Player the Con- 
troller you specify is added to the list of Controllers managed by the 
Player. Conversely, when you call removeCont roller, the specified Con- 
troller is removed from the list of managed Control 1 ers. 

Typically, when you need to synchronize Players or other Controllers 
you should use this addController mechanism. It is simpler, faster, and' 
less error-prone than attempting to manage synchronized Players indi- 
vidually. 

When a PI ayer assumes control of a Control 1 er: 

• The Controll er assumes the Player object's time base. 

• The Player object's duration becomes the longer of the Controller 
object's duration and its own. If multiple Controllers are placed un- 
der a Player object's control, the Player object's duration is set to 
longest duration. 

• The Player object's start latency becomes the longer of the Controller 
object's start latency and its own. If multiple Control 1 ers are placed 
under a PI ayer object's control, the PI ayer object's start latency is set 
to the longest latency. 

A managing PI ayer only posts completion events for asynchronous meth- 
ods after each of its managed Control 1 ers have posted the event. The 
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managing Player reposte other events generated by the Control! ers as 
appropriate. 3 * 

Adding a Controller 

You use the addController method to add a Controller to the list of Con- 
trol 1 ers managed by a particular PI ayer. To be added, a Cont roll er must 
be m the Realized state; otherwise, a NotReal i zedError is thrown Two 
Players cannot be placed under control of each other. For example if 
pl ayerl is placed under the control of pi ayer2, pi ayer2 cannot be placed 
under the control of pi ayerl without first removing playerl from 
player2's control. 

Once a Controller has been added to a Player, do not call methods 
directly on the managed Controller. To control a managed Controller 
you interact with the managing PI ayer. 

To have pl ayer2 assume control of pl ayerl, call: 
pl ayer2 . addController(pl ayerl) ; 

Controlling Managed Controllers 

To control the operation of a group of Control 1 ers managed by a particu- 
lar Pl ayer, you interact directly with the managing Pl ayer. 

For example, to prepare all of the managed Control 1 ers to start, call 
prefetch on the managing Pl ayer. Similarly, when you want to start them, 
call start on the managing Player. The managing Player makes sure that 
all of the Controll ers are Prefetched, determines the maximum start 
latency among the Controllers, and calls syncStart to start them, specify- 
ing a time that takes the maximum start latency into account. 

When you call a Controller method on the managing Player, the Player 
propagates the method call to the managed Controllers as appropriate. 
Before calling a Control 1 er method on a managed Control 1 er, the Pl ayer 
ensures that the Control 1 er is in the proper state. The following table 
describes what happens to the managed Control! ers when you call con- 
trol methods on the managing Pl ayer. 
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Function 



Stopped Player 



Started Player 



setMediaTime 



setRate 



start 



realize 



prefetch 



stop 



deal 1 ocate 



setStopTime 



syncStart 



close 



Invokes setMediaTime on all man- 
aged Controllers. 



Invokes setRate on all managed 
Controllers. Returns the actual 
rate that was supported by all Con- 
t rollers and set. 



Stops all managed Controllers, in- 
vokes setMediaTime, and restarts 
Controllers. 

Stops all managed Controllers, in- 
vokes setRate, and restarts Control - 
1 ers. Returns the actual rate that 
was supported by all Controllers 
and set. 



Ensures all managed Controllers Depends on the Player implementa- 

are Prefetched and invokes sync- Hon. Player might immediately post 

Start on each of them, taking into a StartEvent. 
account their start latencies. 

The managing PI ayer immediate- The managing PI ayer immediately 



ly posts a RealizeCompleteEvent 
To be added, a Controller must 
already be realized. 

Invokes prefetch on all managed 
Controllers. 



No effect. 



Invokes deallocate on all man- 
aged Controllers. 

Invokes setStopTime on all man- 
aged Controllers. (PI ayer must be 
Realized.) 

Invokes syncStart on all managed 
Controllers. 

Invokes close on all managed 
Controllers. 



posts a Real i zeCompl eteEvent. To be 
added, a Controller must already 
be realized. 

The managing Player immediately 
posts a PrefetchCompl eteEvent, in- 
dicating that all managed Control - 
1 ers are Prefetched. 

Invokes stop on all managed Con- 
trol! ers. 

It is illegal to call deal 1 ocate on a 
Started Player. 

Invokes setStopTime on all managed 
Control 1 ers. (Can only be set once 
on a Started Player.) 

It is illegal to call syncStart on a 
Started Player. 

It is illegal to call close on a Started 
Player. 



Table 3-1: Calling control methods on a managing player. 



Removing a Controller 

You use the removeCont roller method to remove a Controller from the 
list of controllers managed by a particular PI ayer. 
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To have pi ayer2 release control of pi ayerl, call: 
pi ayer2 . removeCont rol 1 er (pi ayerl) ; 

Synchronizing Players Directly 

In a few situations, you might want to manage the synchronization of 
multiple PI ayer objects yourself so that you can control the rates or media 
times independently. If you do this, you must: 

1. Register as a listener for each synchronized PI ayer. 

2. Determine which Player object's time base is going to be used to drive 
the other Player objects and set the time base for the synchronized 
Player objects. Not all Player objects can assume a new time base. 
For example, if one of the PI ayer objects you want to synchronize has 
a push data-source, that Player object's time base must be used to 
drive the other Player objects. 

3. Set tine rate for all of the PI ayer s. If a PI ayer cannot support the rate you 
specify, it returns the rate that was used. (There is no mechanism for 
querying the rates that a PI ayer supports.) 

4. Synchronize the states of all of the PI ayer objects. (For example, stop all 
of the players.) 

5. Synchronize the operation of the Player objects: 

• Set the media time for each PI ayer. 

• Prefetch each PI ayer. 

• Determine the maximum start latency among the synchronized 
Player objects. 

• Start the Player objects by calling syncStart with a time that takes 
into account the maximum latency. 

You must listen for transition events for all of the PI ayer ob j ects and 
keep track of which ones have posted events. For example, when you 
prefetch the Player objects, you need to keep track of which ones have 
posted PrefetchComplete events so that you can be sure all of them are 
Prefetched before calling syncStart. Similarly, when you request that the 
synchronized PI ayer objects stop at a particular time, you need to listen 
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for the stop event posted by each PI ayer to determine when all of them 
have actually stopped. 

In some situations, you need to be careful about responding to events 
posted by the synchronized PI ayer objects. To be sure of the state of all of 
the PI ayer objects, you might need to wait at certain stages for all of them 
to reach the same state before continuing. 

For example, assume that you are using one PI ayer to drive a group of 
synchronized PI ayer objects. A user interacting with that PI ayer sets the 
media time to 10, starts the PI ayer, and then changes the media time to 20. 
You then: 

1. Pass along the first setMedi aTi me call to all of the synchronized PI ayer 
objects. 

2. Call prefetch on each Player to prepare them to start. 

3. Call stop on each PI ayer when the second set media time request is re- 
ceived. 

4. Call setMedi aTi me on each Player with the new time. 

5. Restart the prefetching operation. 

6. When all of the PI ayer objects have been prefetched, start them by call- 
ing syncStart, taking into account their start latencies. 

In this case, just listening for Pref etchComplete events from all of the 
Player objects before calling syncStart isn't sufficient. You can't tell 
whether those events were posted in response to the first or second 
prefetch operation. To avoid this problem, you can block when you call 
stop and wait for all of the PI ayer objects to post stop events before con- 
tinuing. This guarantees that the next PrefetchComplete events you 
receive are the ones that you axe really interested in. 

Example: Playing an MPEG Movie in an Applet 

The sample program PI ayerAppl et demonstrates how to create a PI ayer 
and present an MPEG movie from within a Java applet. This is a general 
example that could easily be adapted to present other types of media 
streams. 
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The PI ayer object' s visual presentation and its controls are displayed 
within the applet 7 s presentation space in the browser window. If you cre- 
ate a Player in a Java application, you are responsible for creating the win- 
dow to display the Player object's components. 

Note: While PI ayerAppl et illustrates the basic usage of a PI ayer, it does 
not perform the error handling necessary in a real applet or application. 
For a more complete sample suitable for use as a template, see "JMF 
Applet" on page 173. 

Overview of PlayerApplet 

The APPLET tag is used to invoke Pi ayerAppl et in an HTML file. The WIDTH 
and HEIGHT fields of the HTML APPLET tag determine the dimensions of the 
applet's presentation space in the browser window. The PARAM tag identi- 
fies the media file to be played. 



Example 3-5: Invoking PI ayerAppl et. 




When a user opens a web page containing PI ayerAppl et, the applet loads 
automatically and runs in the specified presentation space, which contains 
the PI ayer objecf s visual component and default controls. The PI ayer 
starts and plays the MPEG movie once. The user can use die default 
PI ayer controls to stop, restart, or replay the movie. If the page containing 
the applet is closed while the PI ayer is playing the movie, the PI ayer auto- 
matically stops and frees the resources it was using. 

To accomplish this, PI ayerAppl et extends Appl et and implements the Con- 
trol lerListener interface. PlayerApplet defines five methods: 

• i ni t — creates a PI ayer for the file that was passed in through the PARAM 
tag and registers PI ayerAppl et as a controller listener so that it can ob- 
serve media events posted by the PI ayer. (This causes the PI ayerAp- 
pl et control 1 er Update method to be called whenever the PI ayer posts 
an event.) 

• start — starts the PI ayer when PI ayerAppl et is started. 

• stop — stops and deallocates the PI ayer when PI ayerAppl et is 
stopped. 

• destroy — closes the PI ayer when PI ayerAppl et is removed. 
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• control 1 erUpdate— responds to PI ayer events to display the PI ayer 
objecf s components. 

Example 3-6: PlayerApplet. 
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Initializing the Applet 

When a Java applet starts, its init method is invoked automatically. You 
override init to prepare your applet to be started. PlayerApplet performs 
four tasks in init: 

1. Retrieves the applef s FILE parameter. 

2. Uses the FILE parameter to locate the media file and build a URL object 
that describes that media file. 

3. Creates a PI ayer for the media file by calling Manager.createPI ayer. 

4. Registers the applet as a controller listener with the new PI ayer by call- 
ing addControl 1 erLi stener. Registering as a listener causes the PI ayer- 
Appl et cont rol 1 erUpdate method to be called automatically whenever 
the Player posts a media event. The Player posts media events when- 
ever its state changes. This mechanism allows you to control the PI ayer 
object's transitions between states and ensure that the Player is in a 
state in which it can process your requests. (For more information, see 
"Player States" on page 26.) 



Example 3-7: Initializing PlayerApplet. 
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Controlling the Player 

The Applet class defines start and stop methods that are called automati- 
cally when the page containing the applet is opened and closed. You over- 
ride these methods to define what happens each time your applet starts 
and stops. 

PI ayerAppl et implements start to start the PI ayer whenever the applet is 
started. 
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Similarly PI ayerAppl et overrides stop to stop and deallocate the PI ayer: 
Example 3-9: Stopping the PI ayer in PI ayerAppl et. 




wmmm 




Deallocating the PI ayer releases any resources that would prevent another 
PI ayer from being started. For example, if the PI ayer uses a hardware 
device to present its media, deallocate frees that device so that other 
Players can use it. 

When an applet exits, destroy is called to dispose of any resources created 
by the applet. PI ayerAppl et overrides destroy to close the PI ayer. Closing 
a PI ayer releases all of the resources that if s using and shuts it down per- 
manently. 
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Responding to Media Events 

PI ayerAppl et registers itself as a Control 1 erLi stener in its i ni t method so 
that it receives media events from the PI ayer. To respond to these events, 
PI ayerAppl et implements the control! erUpdate method, which is called 
automatically when the PI ayer posts an event. 

PI ayerAppl et responds to one type of event, Real i zeCompl eteEvent. When 
the Player posts a Real i zeCompl eteEvent, PI ayerAppl et displays the 
Player object's components. 



Example 3-11: Responding to media events in PI ayerAppl et. 




A PI ayer objecf s user-interface components cannot be displayed until the 
Player is Realized; an Unrealized Player doesn't know enough about its 
media stream to provide access to its user-interface components. PI ayer- 
Appl et waits for the PI ayer to post a Real i zeCompl eteEvent and then dis- 
plays the PI ayer objecf s visual component and default control panel by 
adding them to the applet container. Calling vali date triggers the layout 
manager to update the display to include the new components. 

Presenting Media with the MediaPlayer Bean 

Using the Medi aPl aye r Java Bean (javax . medi a . bean . pi aye rbean . Medi a- 
Pl ayer) is the simplest way to present media streams in your applets and 
applications. Medi aPl ayer encapsulates a full-featured JMF PI ayer in a 
Java Bean. You can either use the Medi aPl ayer bean's default controls or 
customize its control Components. 

One key advantage to using the MediaPlayer bean is that it automatically 
constructs a new Player when a different media stream is selected for 
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Media Streams 



To send or receive a live media broadcast or conduct a video conference 
over the Internet or Intranet, you need to be able to receive and transmit 
media streams in real-time. This chapter introduces streaming media cor 
cepts and describes the Real-time Transport Protocol JMF uses for receiv- 
ing and transmitting media streams across the network. 



Streaming Media 

When media content is streamed to a client in real-time, the client can 
begin to play the stream without having to wait for the complete stream to 
download. In fact, the stream might not even have a predefined dura- 
tion—downloading the entire stream before playing it would be impossi- 
ble. The term streaming media is often used to refer to both this technique of 
delivering content over the network in real-time and the real-time media 
content thafs delivered. 

Streaming media is everywhere you look on the web— live radio and tele- 
vision broadcasts and webcast concerts and events are being offered by a 
rapidly growing number of web portals, and ifs now possible to conduct 
audio and video conferences over the Internet. By enabling the delivery of 
dynamic, interactive media content across the network, streaming media 
is changing the way people communicate and access information. 

Protocols for Streaming Media 

Transmitting media data across the net in real-time requires high network 
throughput. If s easier to compensate for lost data than to compensate for 
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large delays in receiving the data. This is very different from accessing 
static data such as a file, where the most important thing is that all of the 
data arrive at its destination. Consequently the protocols used for static 
data don t work well for streaming media. 

The HTTP and FTP protocols are based on the Transmission Control Pro- 
tocol (TCP). TCP is a transport-layer protocol 1 designed for reliable data 
communications on low-bandwidth, high-enor-rate networks. When a 
packet is lost or corrupted, if s retransmitted. The overhead of guarantee- 
ing reliable data transfer slows the overall transmission rate. 

For this reason, underlying protocols other than TCP are typically used for 
streaming media. One that* s commonly used is the User Datagram Proto- 
col (UDP). UDP is an unreliable protocol; it does not guarantee that each 
packet will reach its destination. There's also no guarantee that the pack- 
ets will arrive in the order that they were sent. The receiver has to be able 
to compensate for lost data, duplicate packets, and packets that arrive out 
of order. 

Like TCP, UDP is a general transport-layer protocol— a lower-level net- 
working protocol on top of which more apphcation-specific protocols are 
built. The Internet standard for transporting real-time data such as audio 
and video is the Real-Time Transport Protocol (RTP). 

RTP is defined in IETF RFC 1889, a product of the AVT working group of 
the Internet Engineering Task Force (IETF). 



Real-Time Transport Protocol 

RTP provides end-to-end network delivery services for the transmission 
of real-time data. RTP is network and transport-protocol independent, 
though it is often used over UDP. 



In the seven layer ISO/ OSI data communications model, the transport layer is level 
four. For more information about the ISO/OSI model, see Understanding OSI. 
Larmouth, John. International Thompson Computer Press, 1996. ISBN 1850321760. 
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Figure 7-1: RTP architecture. 

KIP can be used over both unicast and multicast network services. Over a 
umcast network service, separate copies of the data are sent from the 
source to each destination. Over a multicast network service, the data is 
sent from the source only once and the network is responsible for trans- 
mitting the data to multiple locations. Multicasting is more efficient for 
many multimedia applications, such as video conferences. The standard 
Internet Protocol (IP) supports multicasting. 

RTP Services 

RTP enables you to identify the type of data being transmitted, determine 
what order the packets of data should be presented in, and synchronize 
media streams from different sources. 

RTP data packets are not guaranteed to arrive in the order that they were 
sent— m fact, they're not guaranteed to arrive at all. It's up to the receiver 
to reconstruct the sender 's packet sequence and detect lost packets using 
the information provided in the packet header. 

While RTP does not provide any mechanism to ensure timely delivery or 
provide other quality of service guarantees, it is augmented by a control 
protocol (RTCP) that enables you to monitor the quality of the data distri- 
bution. KTCP also provides control and identification mechanisms for 
RTP transmissions. 

If quality of service is essential for a particular application, RTP can be 
used over a resource reservation protocol that provides connection-ori- 
ented services. 
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RTP Architecture 

2* m "a 8 ««mg a set of applications communicat- 

dohT^^^ 86881 ^ 18 by 3 network address ^ a pair of 

CKTC^ ° S ^ df0rAemediadate ^ d * e ^risusedforcontrol 

A participant is a single machine, host, or user participating in the session 
Participation in a session can consist of passive reception of data 
(receiver), active transmission of data (sender), or both. 

Each media type is transmitted in a different session. For example, if both 
audio and video are used in a conference, one session is used to transmit 
ttje audio data and a separate session is used to transmit the video data 
This enables participants to choose which media types they want to 
receive— for example, someone who has a low-bandwidth network con- 
nection might only want to receive the audio portion of a conference. 

Data Packets 

The media data for a session is transmitted as a series of packets. A series 
of data packets that originate from a particular source is referred to as an 
FTP stream. Each RTP data packet in a stream contains two parts, a struc- 
tured header and the actual data (the packer's payload). 

BitO 1 2 3 4 5 6 7 8 9 0 1 2 3 4 S 16 7 8 9 0 1 2 3 4 S 6 7 8 9 0 31 
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PT 



Sequence Number 



Tlmestamp 



Synchronization Source (SSRC) 



Content Source (CSRC) 
(0-15) 



Figure 7-2: RTP data-packet header format. 

The header of an RTP data packet contains: 

• The RTP version number (V): 2 bits. The version defined by the cur- 
rent specification is 2. 
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• Padding ; CP* r bit If the padding bit is set, there are one or more bytes 
at the end of the packet that are not part of the payload. The very last 
byte in the packet indicates the number of bytes of padding The 
padding is used by some encryption algorithms. 

• Extension (X): 1 bit. If the extension bit is set, the fixed header is fol- 
lowed by one header extension. This extension mechanism enables 
implementations to add information to the RTP Header. 

• 2? « C t bitS ' 1116 number of CSRC identifiers that follow 
the fixed header If the CSRC count is zero, the synchronization source 
is the source of the payload. 

• Marker (M): 1 bit. A marker bit defined by the particular media 
profile. 

• Payload Type (FT): 7 bits. An index into a media profile table that 
describes the payload format. The payload mappings for audio and 
video are specified in RFC 1890. 

• Sequence Number: 16 bits. A unique packet number that identifies 
this packef s position in the sequence of packets. The packet number 
is incremented by one for each packet sent. 

• Timestamp: 32 bits. Reflects the sampling instant of the first byte in 
the payload. Several consecutive packets can have the same 
timestamp if they are logically generated at the same time—for 
example, if they are all part of the same video frame. 

• SSRC 32 bits. Identifies the synchronization source. If the CSRC count 
is zero, the payload source is the synchronization source. If the CSRC 
count is nonzero, die SSRC identifies the mixer. 

• CSRC: 32 bits each. Identifies the contributing sources for the payload. 
The number of contributing sources is indicated by the CSRC count 
field; there can be up to 16 contributing sources. If there are multiple 
contributing sources, the payload is the mixed data from those 
sources. 
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Control Packets 

In addition to the media data for a session, control data (RTCP) packets 
are sent periodically to all of the participants in the session. RTCP packets 
can contain information about the quality of service for the session partic- 
ipants, information about the source of the media being transmitted on the 
data port, and statistics pertaining to the data that has been transmitted so 
far. 
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There are several types of RTCP packets: 

• Sender Report 

• Receiver Report 

• Source Description 

• Bye 

• Application-specific 

RTCP packets are "stackable" and are sent as a compound packet that con- 
tains at least two packets, a report packet and a source description pacTt. 

All participants in a session send RTCP packets. A participant that has 
recently sent data packets issues a sender report. The sender report (SR) 
contains the total number of packets and bytes sent as well as information 
that can be used to synchronize media streams from different sessions. 

Session participants periodically issue receiver reports for all of the sources 
from which they are receiving data packets. A receiver report (RR) con- 
tarns information about the number of packets lost, the highest sequence 
number received, and a timestamp that can be used to estimate the round- 
tnp delay between a sender and the receiver. 

The first packet in a compound RTCP packet has to be a report packet 
even if no data has been sent or received— in which case, an empty ' 
receiver report is sent. 

All compound RTCP packets must include a source description (SDES) 
element that contains the canonical name (CNAME) that identifies the 
source. Additional information might be included in the source descrip- 
tion, such as the source's name, email address, phone number, geographic 
location, application name, or a message describing the current state of the 
source. 



When a source is no longer active, it sends an RTCP BYE packet. The BYE 
notice can include the reason that the source is leaving the session. 

RTCP APP packets provide a mechanism for applications to define and 
send custom information via the RTP control port. 

RTP Applications 

RTP applications are often divided into those that need to be able to 
receive data from the network (RTP Clients) and those that need to be able 
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£STS1 i ? e nCtWOrk (KrPServe «)- Some applications do 
l ^u' C °^ rendn S ^plications capture and transmit data 
at the same time that they're receiving data from the network. 

Receiving Media Streams From the Network 

• Conferencing applications need to be able to receive a media stream 
from an RTF session and render it on the console. 

• A telephone answering machine application needs to be able to 
receive a media stream from an RTP session and store it in a file. 

• An application that records a conversation or conference must be able 
to receive a media stream from an RTP session and both render it on 
the console and store it in a file. 

Transmitting Media Streams Across the Network 

RTP server applications transmit captured or stored media streams across 
the network. 

For example, in a conferencing application, a media stream might be cap- 
tured from a video camera and sent out on one or more RTP sessions. The 
media streams might be encoded in multiple media formats and sent out 
on several RTP sessions for conferencing with heterogeneous receivers. 
Multiparty conferencing could be implemented without IP multicast by 
using multiple unicast RTP sessions. 



References 

The RTP specification is a product of the Audio Video Transport (AVT) 
working group of the Internet Engineering Task Force (IETF). For addi- 
tional information about the IETF, see http : //www. i etf . org. The AVT 
working group charter and proceedings are available at 
http : //www. ietf. org/html . charters/avt-charter . html . 

IETF RFC 1889, RTP: A Transport Protocol for Real Time Applications 
Current revision: http://www. ietf .org. internet-drafts/draft-ietf- 
avt- rtp-new-04 . txt 
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IETFRFC 1890: RTP Profile for Audio and Vtdeo Conferences unth Minimal 

Current revision: http://www.Tetf . org.internet-drafts/draft-ietf- 
avt-profile-new-06.txt 

^f? 65 ^ 5 ^jnte&toZ revisions in preparation for advance- 
ment from Proposed Standard to Draft Standard arid the URLs listed here 
arefor the Internet Drafts of the revisions available at the time :of public 

In addition to these RFCs, separate payload specification documents 
r^to° W P aiticuiai Payloads are to be carried in RTP. For a list of all of 
the RTP-related specifications, see the AVT working group charter af 
http : //www . i etf . org/html . charters/avt-charter . html . 



Understanding the JMF 

RTP API 



JMF gables the playback and transmission of RTP streams through the 
APIs defined in the javax.media. rtp, javax.media. rtp.event, and 
l 3 ^"^ 1 a " rtp - rtcp P acka S es - JMF can be extended to support addi- 
taonal RTP-spedfic formats and dynamic payloads through the standard 
JMF plug-in mechanism. 

Note JMF-compIiant implementations are not required to support the 
KTP APIs in javax.media. rt P/ javax.media. rtp. event, and 
javax. media, rtp. rtcp. The reference implementations of JMF provided bv 
bun Microsystems, Inc. and IBM Corporation fully support these APIs. 

You can play incoming RTP streams, locally save them to a file, or both. 




Figure 8-1: RTP reception. 

For example, the RTP APIs could be used to implement a telephony appli- 
cation that answers calls and records messages like an answering machine. 

Similarly, you can use the RTP APIs to transmit captured or stored media 
streams across the network. Outgoing RTP streams can originate from a 
file or a capture device. The outgoing streams can also be played locallv 
saved to a file, or both. J ' 
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Figure 8-2: RTP transmission. 

For example, you could implement a video conferencing application that 
captures hve audio and video and transmits it across thf nKkSne a 
separate RTP session for each media type. USmg a 

Similarly, you might record a conference for later broadcast or use a prere- 
corded audio stream as "hold music" in a conferencing application. 

RTP Architecture 

The JMF RTP APIs are designed to work seamlessly with the capture, pre- 
sentation, and processing capabilities of JMF. Players and processors are 
used to present and manipulate RTP media streams just like any other 
media content. You can transmit media streams that have been captured 
from a local capture device using a capture DataSource or that have been 

^ * 3 DataSi nk - Similar ^ JMF can be extended to support 

additional RTP formats and payloads through the standard plug-in mech- 
anism. 





Packetizei 
Codecs 



Figure 8-3: High-level JMF RTP architecture. 
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Session Manager 

In JMF, a SessionManager is used to coordinate an RIP session The session 

The session manager maintains the state of the session as viewed from the 
local participant. In effect, a session manager is a local representation^ t 
d.tabutedentity, the RTP session. The session rn^ll^Ts t 
RTCP control channel, and supports RTCP for both senders and receivers. 

2?fn?« S i Si ° nMa 4 na f f interfaCe defines methods mat ena We an application 
created by the application, and close the entire session. 

Session Statistics 

The session manager maintains statistics on all of the RTP and RTCP pack 
ets sent and received in the session. Statistics are tracked for the entire ses- 
sion on a per-stream basis. The session manager provides access to global 
reception and transmission statistics: 

• ClobalReceptionStats: Maintains global reception statistics for the 
session. 

• CTobalTransnnssionStats: Maintains cumulative transmission statis- 
tics for all local senders. 

Statistics for a particular recipient or outgoing stream are available from 
the stream: 

• ReceptionStats: Maintains source reception statistics for an individu- 
al participant. 

• TransmissionStats: Maintains transmission statistics for an individual 
send stream. 



Session Participants 

Thesession manager keeps track of all of the participants in a session 
Each participant is represented by an instance of a class that implements 
the Participant interface. SessionManagers create a Participant when- 
ever an RTCP packet arrives that contains a source description (SDES) 
with a canonical name(CNAME) that has not been seen before in the sessioi 
(or has timed-out since its last use). Participants can be passive (sending 
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control I packets only) or active (also sending one or more RIP data 

■ttere is exactly one local participant that represents the local client/server 
partapant A local participant indicates that it will begin 

messages oy starting a session. 

A participant can own more than one stream, each of which is identified 
by the synchronization source identifier (SSRC) used by the sourcTof te 



Session Streams 



The SessionManager maintains an RTPStream object for each stream of RIP 
data packets in the session. There are two types of RTP streams: 

• Recei vest ream represents a stream that's being received from a remote 
participant. 

• SendStream represents a stream of data coining from the Processor or 
input DataSource that is being sent over the network. 

A Recei veStream is constructed automatically whenever the session man- 
ager detects a new source of RTP data. To create a new SendStream, you 
call the SessionManager createSendStreara method. 

RTP Events 

Several RTP-specific events are defined in javax. medi a. rtp. event These 
events are used to report on the state of the RTP session and streams. 
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■ [ LocalConisionEvent j 
- | NewParti ci pantEvent j 



Figured: RTP events. 

To receive notification of RTP events, you implement the appropriate RTP 
listener and register it with the session manager: 

• SessionListener: Receives notification of changes in the state of the 
session. 
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Session Listener 

You ™l*™n*^s1onl.1 stener to receive notification about events 
tor P«tem to the KIP session as a whole, such as the addition of new 

There are two types of session-wide events: 

• ^on tiCiPantEVent: IndiCateS * ata new P^ P ant has joined the 

• ^CollisionEventrmdi^ 

source is already in use. 1 

Send Stream Listener 

You can implement SendStreamLi stener to receive notification whenever: 

• New send streams are created by the local participant. 

• The transfer of data from the DataSource used to create the send 
stream has started or stopped. 

• The send stream's format or payload changes. 

There are five types of events associated with a SendStream: 

• N^SendStreanEvent: Indicates that a new send stream has been creat- 
ed by the local participant. 

• Acti veSendStreaaEvent: Indicates that the transfer of data from the 
DataSource used to create the send stream has started. 

• InactiveSendStreamEvent: Indicates that the transfer of data from the 
DataSource used to create the send stream has stopped. 

• Local PayloadChangeEvent: Indicates that the stream's format or pay- 
load has changed. 
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• StreamClosedEvent: Indicates that the stream has been closed. 
Receive Stream Listener 

Youcan implement ReceiveStreamLlstener to receive notification when- 

• New receive streams are created. 

• The transfer of data starts or stops. 

• The data transfer times out. 

• ApreviouslyorphanedReceiveStreamhasbeenassociated witha Par- 
ticipant. 

• An RTCPAPP packet is received. 

• The receive stream's format or payload changes. 

You can also use this interface to get a handle on the stream and access the 
DataSource so that you can create a Medi aHandler. 

There are seven types of events associated with a Recei veStream: 

• NewRecei veStreamEvent: Indicates that the session manager has creat- 
ed a new receive stream for a newly-detected source. 

• Acti veReceiveStreamEvent : Indicates that the transfer of data has 
started. 

• InactiveReceiveStreamEvent: Indicates that the transfer of data has 
stopped. 

• TineoutEvent: Indicates that the data transfer has timed out. 

• RemotePayloadChangeEvent: Indicates that the format or payload of the 
receive stream has changed. 

• StreamMappedEvent: Indicates that a previously orphaned receive 
stream has been associated with a participant. 

• Appl lcationEvent: Indicates that an RTCP APP packet has been 
received. 

Remote Listener 



or 



You can implement RemoteLi stener to receive notification of events ^ 
RTP control messages received from a remote participants. You might 
want to implement RemoteLi stener in an application used to monitor the 
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session-it enables you to receive RTCP reports and monitor the aualitv of 
ea™ m reCePti0n ^ ^ t0 ^ VC data ° r fato-SSS? 
There are three types of events associated with a remote participant: 

* "e"elv V ed rReP ° rtEVent ** RTP receiver re P°* ^as been 

• RemoteOoll isionEvent: Indicates that two remote participants are 
using the same synchronization source ID (SSRC). 

RTP Data 

The streams within an RTP session are represented by RTPStream objects 
There are two types of RTPStreams: Recei veStrea* and SendStream. Each' 
Kl r stream has a buffer data source associated with it. For Recei veS- 
treams, this DataSource is always a PushBufferDataSource. 

The session manager automatically constructs new receive streams as it 
detects additional streams arriving from remote participants. You con- 
struct new send streams by calling createSendStream on the session man- 
ager. 



Data Handlers 

The JMF RTP APIs are designed to be transport-protocol independent A 
custom RTP data handler can be created to enable JMF to work over a spe- 
cific transport protocol. The data handler is a DataSource that can be used 
as the media source for a PI ayer. 

The abstract class RTPPushDataSource defines the basic elements of a JMF 
RTP data handler. A data handler has both an input data stream (Push- 
SourceStream) and an output data stream (OuputDataStream). A data han- 
dler can be used for either the data channel or the control channel of an 
RTP session. If it is used for the data channel, the data handler implements 
the DataChannel interface. 

An RTPSocket is an RTPPushDataSource has both a data and control chan- 
nel. Each channel has an input and output stream to stream data to and 
from the underlying network. An RTPSocket can export RTPControl s to 
add dynamic payload information to the session manager. 
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Because a custom RTPSocket can be used to construct a PI ayer through the 
Manager, JMF defines the name and location for custom RTPSocSp£ 
mentations: ul r lc 

protocol package-prefix>.media.protocol .rtpraw.DataSource 
RTP Data Formats 

*! fJT dfiC da ? ^ RTP - S P edfic foimat ^coding as defined in 
l^tT ^deoFormat classes. For example, gsm RTP encapsu- 
lated packets have the encoding set to AudioFormat.CSM.RTP, while ipe*- 
encoded video formats have the encoding set to VideoForraat . JPEG_RTP. 

AudioFormat defines four standard RTP-specific encoding strings: 

public static final String ULAW.RTP = "JAUDI0_G711 ULAW/rto"- 

public static final String DVT_RTP = "dvi/rtp"; ~ 

public static final String G723_RTP = "g723/rtp"- 

public static final String GSM_RTP = "gsm/rtp"; 

Vi deoFormat defines three standard RTP-specific encoding strings: 

public static final String JPEG_RTP - "jpeg/rtp"; 
public static final String H261_RTP = "h261/rtp" • 
public static final String H263_RTP = M h263/rtp"; 

RTP Controls 

The RTP API defines one RTP-specific control, RTPControl. RTPControl is 
typically implemented by RTP-specific DataSources. It provides a mecha- 
nism to add a mapping between a dynamic payload and a Format. RTPCon- 
trol also provides methods for accessing session statistics and getting the 
current payload Format. 

SessionManager also extends the Controls interface, enabling a session 
manager to export additional Controls through the getControl and get- 
Control s methods. For example, the session manager can export a Buffer- 
Control to enable you to specify the buffer length and threshold. 



Reception 



The presentation of an incoming RTP stream is handled by a PI ayer. To 
receive and present a single stream from an RTP session, you can use a 
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MediaLocator that describes the session to construct a Player Amedia 
locator for an RIP session is of the form: 

rtp://address:port[:ssrc]/content-type/[ttl] 
The PI ayer is constructed and connected to the first stream in the session. 
If there are multiple streams in the session that you want to present you 
need to use a session manager. You can receive notification from the ses- 
sion manager whenever a stream is added to the session and construct a 
PI ayer for each new stream. Using a session manager also enables you to 
directly monitor and control the session. »youto 

Transmission 

A session manager can also be used to initialize and control a session so 
that you can stream data across the network. The data to be streamed is 
acquired from a Processor. 

For example, to create a send stream to transmit data from a live capture 
source, you would: F 

1. Create, initialize, and start a SessionManager for the session. 

2. Construct a Processor using the appropriate capture DataSource. 

3. Set the output format of the Processor to an RTP-specific format. An 
appropriate RTP packetizer codec must be available for the data format 
you want to transmit. 

4. Retrieve the output DataSource from the Processor. 

5. Call createSendStream on the session manager and pass in the Data- 
Source. 

You control the transmission through the SendStream start and stop 
methods. 

When it is first started, the SessionManager behaves as a receiver (sends 
out RTCP receiver reports). As soon as a SendStream is created, it begins to 
send out RTCP sender reports and behaves as a sender host as long as one 
or more send streams exist. If all SendStreams are closed (not just stopped) 
the session manager reverts to being a passive receiver. 
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Extensibility 

^ded^Kr^ R1P u ca P aMities can be enhanced and 
AA? **** SUpP ° rt a basic *>f RTP formats and payloads 

Advanced developers and technology providers can implement^ 
plug-ins to support dynamic payloads and additional RTP formats. 

Implementing Custom Packetizers and Depacketizers 

^£r en ! IT'T P acketizer or depacketizer, you implement the 
JMF Codec interface. (For general information about JMF P W-ins see 
Implementing JMF Plug-Ins" on page 85.) P g 
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Receiving and Presenting 
RTP Media Streams 



JMF Players and Processors provide the presentation, capture, and data 
conversion mechanisms for RTP streams. 




Figure 9-1: RTP reception data flow. 

A separate player is used for each stream received by the session manager 
You construct a Player for an RTP stream through the standard Manager 
createPl ayer mechanism. You can either 

• Use a Medi aLocator that has the parameters of the RTP session and 
constructa Player by calling Manager. createPl ayer (MediaLocator) 

• Construct a Player for a particular ReceiveStream by retrieving the 
DataSource from the stream and passing it to Manager . createPlay- 
er(DataSource). 

SSS^i Med1J t°5 at f r to construct a player - y° u can onl y p resent 

\1 fY^Z™ S deteCted in me aeaa ° D - K y° u want to play back 
multiple RTP streams in a session, you need to use the SessionManager 
directly and construct a Player for each ReceiveStream. 
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Creating a Player for an RTP Session 

When you use a MediaLocator to construct a Player for an RIP session 
Ae Manager creates a Mayer for the first stream detected^ me sSon 

By listening for the Real izeCompleteEvent, you can determine whether or 
no any data has arrived and if the PI aye r is capable of p^nfot ^v 

tiof^ 

ateRealizedPHayer to construct a Player for otSSSS^n^ 
Player would be returned until data arrives and if no data is ducted at 
tempting to create a Realized Player would block indefStely ' 

A PI ayer can export one RTP-specific control, RTPControl, which provides 





Listening for Format Changes 

When a PI ayer posts a FormatChangeEvent, it might indicate that a payload 
change has occurred. Payers constructed with a MediaLocator automati- 
caUyprocess payload changes. In most cases, this processing involves con- 
structinganew PI ayer to handle the new format. Applications that 
present RTP media streams need to listen for FormatChangeEvents so that 
they can respond if a new PI ayer is created. 

When a FormatChangeEvent is posted, check whether or not the Player 
ob^cfs control and visual components have changed. If they have, a new 
Player has been constructed and you need to remove references to the old 
Player object's components and get the new PI ayer object's components. 
Example 9-2: Listening for KIP format changes (1 of 2) 
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Creating an RIP Player for Each New Receive Stream 

To play all of the Recei veStreams in a session, you need to create a sepa- 
rate Player for each stream. When a new stream is created, the session 
manager posts a NewRecei veStreamEvent. Generally you register as a 
Recei veStreamListener and construct a Player for each new ReceiveS- 
tream. To construct the Player, you retrieve the DataSource from the 
Recei veStream and pass it to Manager . createPl ayer. 

To create a PI ayer for each new receive stream in a session: 
1. Set up the RTP session: 

a. Create a SessionManager. For example, construct an instance of 
com. sun. media. rtp.RTPSessionMgr. (RTPSessionMgr isanimple- 
mentation of SessionManager provided with the JMF reference 
implementation.) 



b. Call RTPSesslonMgr addRecelveStr^u 
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stener to register as a lis- 
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In your ReceiveStreamListener update method, watch for NewRe- 
cei vest reamEvent, which indicates that a new data stream has been de- 
tected. 



3. When a NewRecei vest reamEvent is detected, retrieve the ReceiveStream 
from the NewRecei veStreamEvent by calling getReceiveStream. 

4. Retrieve the RTP DataSource from the ReceiveStream by calling get- 
DataSource. This is a PushBufferDataSource with an RTP-specific For- 
mat. For example, the encoding for a DVI audio player will be DVI_RTP. 

5. Pass the DataSource to Manager. createPI aver to constructa Player. For 
the PI ayer to be successfully constructed, the necessary plug-ins for de- 
coding and depacketizing the RTP-formatted data must be available. 
(For more information, see "Creating Custom Packetizers and Depack 
etizers" on page 167). 



Receiving and Presenting RTP Media Streams 




See RTPUtil in "KTPUtil" on page 223 for a complete example. 
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Chaptei l. WebSphere applications 



This chapter provides an overview of WohQnH^ 
this chapter we take a took^?„^^£ ^cations. Throughout 
used to form applications, achat's SS^S,* *™ com P° nen * «re 
monitor applications. ° ed,t ' mana 9 e - de P'oy. fun and 



1.1 What is an application? 



An application in the context of Web<3nhar« i* « ~ .. 

resources. Some examoles of Z a P ? S 3 collect,on <* user-supplied 



1-2 What is a servlet? 



the capabiti,, 0( being written „ nc8 .£ ™ a^J. 

on the server. Jus. the fan teX P,O0ram ,lke an "PPtot, runs 

Servlets can then exercise a lot m «« ~ 7 ■ ° the server ^ resources, 
sent out to the cltente ^adc InZ-T 0 " ^ informa,ion shouW °* 
9 raphica„ y visi b ,e fo ~ - * 
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associated classes and mS^^l^^S^ 4 a,0n9 the 
servers. Servlets can also use addTtSnauL»T * m ° St major Web 
extend the Java Servlet API?" C,3SSes and P a <*ages to 

Servlets communicate throuah remote «„w 
behavior of HyperText Tracer P^ir™^*^ f ° ,he 
engine running on a Web server by usl thY«" * mteraCt with a servlet 
exampie, when a client sendsTrequesUo TSZZXT? For 
request information onto the servlet and hJ« ,1 ' 6 Server 080 send »» 
*» a response wnlcn ^U^r^SSSSK" " W 



Internet Banking 
Front-End 



Websphere 
Server 




HflQueat Account aapanctt 



RrtunKTMLpagewMh 
feaxxtt Information 





Account Setvfet 
ftetum Account hformation 



?ntr^S^S~? aPPliCa " 0nS * * « -» 
a ser»let will oomh« b ™ JSL? fT**- Up ° n 

<wnp«e lh 9 servlet code anv ""responding class file. To 

compiles ~JZ^J5ZSZSZ mT n "* 

these files into appropriate directoriTl nl i ' then we nave t0 C0 Py 
the ciass file, J£^2£££^J^ th H e K Java code and 
need to go in the r^t «d£E5S^ — - 

•2.1 Servlet lifecycle 

Each servlet has the same lifecycle It beoins with » ho * 



Apw^aon &»», SoluK ,„ ^ ^ ^ ^ 



handle requests from zero or more clients, until when the server « m 
servlet. nen ine server removes the 

1.2-1.1 Initializing a servlet 

changes their status to available. 8 adm,nistr ato' 

1.2.1.2 Handling client requests 

The service method gets information about the reauest from tho r~, . 
1.2.1.3 Destroying a servlet 
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12.2 Java Servlet API V2.1 overview 

1. An HTTP-specific package 

2. A non-HTTP-specific package 

• javax.servlet 

• javax.servlet.http 

These two packages contain seven interfaces five classes an* ^ 

1.2.3 IBM extensions to the Servlet API V2.1 

In its attempt to make it easier to manage session states and tn , ma( 

V2. 1 . The additional packages and classes are: 

• com.ibm.websphere.servlet.personalization.sessiontracking package 

• c°ni,bm.websphere.servlet.personali2ation.userprofile package 

• com.ibm.websphere.db package 

• c<""ibm.websphere.servlet.error.ServletErrorReport class 

• com.ibm.websphere.servlet.event package 

• com.ibm.websphere.servlet.filter package 

• com.ibm.websphere.servlet.request package 

• com.ibm.websphere.servlet.response package 
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1.2.4 Servlet API V2.1 details 

»£2^££^ ° f ^ ^ *~» AP. V 2 . 1 as we,, as 

V2.1 to make it easier'o ^Lapfge Tssiof^e T«T *~ ^ Serv,et API 

web pa9es ' - « ~ t£ ^ 

com.«bm.websphere.serv.et.persona.lza«lon.3e33lontrac^ 

This package provides the following: 

• Records the referral page that led the visitor to your Web site 

• Tracks the visitor's position within the site. 

• Associates user identification with the session. 

com.ibm.websphere.servlet.perBonallzatlon.userprof.te 

This package provides the following- 

com.lbm.websphere.db package 

This package provides the following: 
• Simplifies access to relational databases 

com.lbm.wrt,»ph.r..«,rvtetem»-.S«vi el Er r o,Bepon class 

com.lbm.websphere.servlet.event package 

This package provides the following: 

• Listener interfaces for notifications of lifecvcle event* for .• 
servers as well as servlet errors. app|,cat.ons and 
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• An interface for registering listeners. 
com.ibm.websphere.servtet.«lter package 
This package provides the following: 

• Support for servlet chaining. 

' ZZSSTJXZ-* to be «»« * « * «. . 

• The ServletChain object. 

• The ChainResponse object. 

com.lbm.websphere.servlet.request package 

This package provides the following: 

• The HttpServletRequestProxy abstract class is used to overload thP 

com.lbm.websphere.servlet.response package 

This package provides the following- 

2.5 Changes to packages supported in WAS V2 

of open data server connections to JDBC or ODBC^™ ma ' nta,ned a P° 0 ' 
al.owed the servlet to c^ical.^^^^S2^ ^ 
connect.cn managed APIs when a coJ^Z^^^T 
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T the Application Server Version 3 now 

«. connect S^E,^ ^ '"^ °' US *" 

££T APP " K " to " S0rw Vere " > " 3 *• •*»«*>■ P"*a 9 «s have pe,„ 



• com.ibm.servfet.personaUzation.sam 

• com.ibm.servlet.serv/ets.personalizabon.utH 



13 What are Enterprise Java beans (EJB)? 

to wrfte EJBs For »hf J ? ^ ' Pr ° Vide a de,ailed Ascription of how 

^^^/^-^-cc^software/webservers/a^serv/iii,^ . html 

1.3.1 Introduction 

EJB components are lightweight, modular and easjto Ej^s ^n b ? 

JavaBeans specifications which can be found at: ms tr "erpnse 

http: //java.sim.cotrVptDducts/ejb/drjcs.hbnl 

^paTe r Ca,eB ° rleS " enterpriSe »-* - —» ■« 
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Figure 2. Categories of enterprise beans 
1.3.1.1 Entity beans 

-»» bean „ U „, q ue, 6ul each ^oan^SS^ZtS °* a " 
(BMP). On the other hand when the container handles the £ta 
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«gurB3. Entity bean life cycle 

Each entity bean consists of the following 4 components- 
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b. 



c. 



Sner CeSSed ^ ** '"-Planted by *, 

1.3.1.2 Session beans 

persistent by using underlying entity beans ' * data 

Every session bean has the following three components: 
• Bean class 



Home interface 
Remote interface 



^ ^ ■* sexes ""sr b,e "» 

Each session bean is associated with one client A session h Mn ■-. . • 
across the methods and is .horSST " ^ 001 maintain data 
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Step 2 




Contamar mv<*«s mjbfr 



Step6 ■ 
Whtn efer* inrdc*. , m^hod on.' 
th» passhwtad boar* th» contain*) 

The bean goes badctothereaoy; 



► . ^ - *"*<)««h«nth« instance «ii 



' hmger requred Thm bun I 




Step7 

When the contort), c^^^, 
c « flf •jbRtfiKWrtO mrtio* the sew ion 
bearfs oycfe ends. 



Figure 4. Session bean Me cycle 
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1-3.2 EJB architecture in brief 

1. EJB server 

lav^A^hn hiteC c re SCh6me ' the EJB server is °* application server 
Hioni « " F ' 9Ure 5 0n pa 9 e 13 - the E JB server connects *r 

aata. The EJB server contains the business logic in the form of J«l 
The reader can find detailed Information on EJB servers In WMno 

sssszxr 1 " ,V965( " w ' 8 ' scm ^ 3 ^ »»< sups «r a 

This book can also be viewed or downloaded from: 

2. Data source 

The persistent data in the entity beans is stored in a recoverable data 
source. For container managed persistence (CMP) the E^e^er 
supports IBM DB2, Oracle, and Microsoft SQL Server and fhe eTb i^L 
(CB) supports DB2, Oracle, IBM CICS and IBM IMS ^ 

F J IS! " t ma " a9ed Persistence (BMP), the user can use any data source 

c^e L he r sis,ent data - The user «^ ■«? z 

code for the beans to handle their own data source interactions 
3. EJB clients 
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The EJB clients can be one or more of the following: Java servlet Java 
apptet-servlet combination, or a JSP file. A Java applet Z7e ^*L * 
serv,e, to interact with the enterprise beans, whi.eh t ^rv er TcB) 
a Java applet can directly interact with the Enterprise Java beaT In an 

d zr^LTz^r r : ionai ejb c,ients « Ess 

rnSL ~ 0RBA ; based Java cl,en ts. and to a limited degree a C++ 
CORBA clients. More details on how to write EJB clients L« £ «tL- „ 

%nwT m mtin9 Enterprise Beans ^SSE" be ob,a,ned 

4. Administration interface 

The EJB server (AE) uses the WebSphere Administrative Console to 
admimster the EJB server. The EJB server (CB) uses the Syslem 
Management End User Interface (SMEUI) 




Figure 5. EJB environment and interaction with other 



components 



1.4 What are JavaServer Pages (JSP) 

JavaServer Pages (JSP) technology provides developers with an easv and 
generate HTML, extensible Markup Language (XML), and other structured 
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1-4.1 JSP process flow 

The JSP process flow is shown in Figure 6 on page 15. 
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Figure 6. JSP process flow 



When WebSphere is installed on top of a Web server, the Web server's 
2S'° n ' S J**"* 10 pass the HTTP quests for the JSP filet to the 
J^P ^i aPP, H at K° n SerVer WebS P her * then passes this request o £ 

comjbm.servlet.jsp.http.pagecompile.PageCompileServlet 
and for JSP 1.0 it is the 

com.sun.jsp.runtimeJspServlet 



Chapter 1 . WebSphere applications 15 



\^2S£2?T B PU !t' he - java and the c,ass inside the 
\WebSphere\AppServer\Temp folder. The location of these files will d en *nw 
on whether you are using JSP 0.91 or JSP 1 .0 in W ^5£S5>T ' 

For example, if you are using JSP 0.91 and the JSP file is in the following 

n,!^^^ tn en the JSP processor will 

Place the .java and the .class files in the following path: prDCessor w "' 

<WASRcot>Memp\examples\pagecompile folder. 

The JSP 0.91 processor uses a naming convention to name these iava anri 
the .class files. If, for example, the JSP filename is JS^oolZt 
processor will name the .java and the .class fi.es as Lp iala a nd 

-s-mple^class, respectively. Under JSP 0.81 the^ £ Ept 

If you are using JSP 1.0 and the JSP file is in the following folder: 

^S^^ then th. JSP processor will 

place the .class files in the following path: processor win 

<WASRoot>\temp\examples 

The JSP 1.0 processor names the .class file simple.class and bv default th* 
sZetn*^ 

£l T u ame kee ra enerat « 1 «sed by the JspServlet to true You 
^ page T 7 MmMs ™™ «nrt, as shownTpigure 7 
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Figure 7. Setting Into Parm Name for JspServlet 



The .java and the .class files generated from the JSP file are servlets 
extending the javax.servIet.http.HttpServlet class. A sample JSP 0.91 file and 
the Java code generated by it is shown in Figure 8 on page 18. 

<HEftN narae^-sinpleSessionMsg" type- " SirapleJSPBean" create- -true" 
soope= " session** >< /BEAN> 

<BEAN nane= H sinpleRequestMsg" type= " SitipleJSPBean- created true" 

scope-" request "></BEMf> 

<% 

SirapleJSPBean sinpleApplicationMsg = 
(SirrpleJSPBean) 

getServletGontextO . getAt tribute ( M s irapleAppl icationMsg" ) ; 
%> 



<htral> 

<head><title>Sinple JSP</titlex/head> 
<body> 
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<iitg sro-hanner.gif alt= "banner image" height=loo width=584xp> 

<hl>siraple JSP page</hl> 

<% if (sinpleApplicatianMsg 1 = null) { %> 

<B>flpplicatian Bean:</B> <%=siitpleA M >licatianMag.getM e seaqe() %><br> 
<% } %> 

<B>Sessian Bean:</B> <%= sinpleSeseianMsg. getMessage ( ) %> <br> 
<B>Request Bean:</B> <%= simpleRequestMsg. getMessage () %> <br> 

</body> 
</html> 



Figures, simple JSP code 0.91 



When this file is processed by the JSP processor, the _simple_xjsp.java file is 
generated. In Figure 9 on page 19, only a snippet of code is shown. Please 
refer to Appendix B, "Sample Code" on page 549, for all of the code and an 
example of the code generated by the JSP 1.0 compiler. 

package pagecompile,- 

import java.io.*; 
import java.util.*; 
import javax. servlet.*; 
import j avax. servlet. http.*; 
import java. beans. Beans; 

inport can . ibra . servlet . j sp . ht tp . pagecoropile . ParamsHt tpServletRequest ; 
import com . ibra . servlet .j sp . ht tp . pagecompile . ServletUt il ; 
import con. ibra. servlet . j sp . ht tp . pagecompile . f ilecache . OiarFileData ; 
import com. ibro.se:nrlet.jsp. http. pagecon^ 

import SimpleJSPBean; 

public class _simple_xjsp extends javax. servlet .http.HttpServlet { 
private static final String sources [] = new String [] { 

"c : \\websphere\\appserver\\hosts\\default_host\\examples\\ 
webWsimple.jsp", 

}; 

private static final long lastModif ied [] = { 
926708647000L, 

b 

public void service (HttpServletRequest request, 
HttpServletResponse response) 
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throws IOException, ServletException 



} 

SirapleJSEBean sinpleSessionMsg- (SimpleJSPBean) 
request . getAttribute ( " sinpleSessianMsg" ) ; 
if ( simpleSessionMsg == null ) 

throw new ServletException ("Invalid BERN name: 
sirapleSessianMsg") * 

{ 

java. util. Properties p - new java.util.PropertiesO ; 
java. util. Enumeration e » request. getParaxneterNames '() 
while (e.hasMoreElementsO) { 

String name = (String) e.nextElement () ; 

p. put (name, request. getParameter (name) ) ; 

com. ita. servlet . util . BeansUtil . eetProperties (sirapleSessionMsg, p) ; 



} 

Figure 9. Code snippet of the __simple_xjsp.java We generated by the JSP processor 

1.4.2 JSPIifecycle 

Since after compilation, JSPs generate a servlet, their life cycle is similar to 
that of a servlet. When the ServletEngine receives a request for a JSP file it 
checks to see if the servlet already exists or if the JSP file has changed since 
the last time it was invoked. If the servlet for the JSP does not exist in the 
application classpath or if the JSP file was changed since the last time it was 
loaded, the servlet engine passes the request to the JSP processor (or the 
pagecompile servlet). This creates another .java and .class file for the 
requested JSP file. These files are placed in the application classpath. The 
servletengine then creates an instance of the class file and calls the servlet 
serviceO method in response to the request. Once the .class and .java files 
have been created by the JSP processor, all the subsequent requests for the 
JSP servlet are handled by the instance of the servlet that was created by the 
servletengine. By default, the JSP syntax in a JSP file is converted to Java 
code by the processor and this code is placed in the service() method of the 
generated class file. This default behavior can be overridden by using the 
method directive in the JSP file. 

The JSP servlet is terminated when the servletengine no longer needs the 
servlet or a new instance of the servlet is being loaded by the servletengine. 
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In doing so, the destroy() method in the servlet is called. If there is a need to 

Z 8 tnI e :T; CeSOr ff the Pr6Vi0US request to tne se^Vo^Z 
also, the servleteng.ne can call the destroy() method of the servlet 

1.4.3 JSP access models 

When using JSPs there are commonly two types of access models used: 

1. JSP file handles both the request and the response 

In this model the JSP file handles both the request and the response to 
and from the client browser. The JSP passes the request to beans or other 

^7a^oV° t gen TV he dynamiC Content - The res P° nse is sent back 
to the JSP file from the beans, which in turn sends it back to the client 
browser. 

2. JSP handles response, servlet handles request 

In this model, the client request is sent to the servlet, which handles the 
dynamic content generation. It then calls a JSP file to send the response 
back to the client Using this model, one can effectively separate the 
business logic from the content display. 

These two JSP access models are discussed in more detail in the redbook 
Patterns for e-business:User to Business Patterns for Topology 1 and 2 usina 
WebSphere Advanced Edition, SG24-5864-00. 

1.4.4 JSP syntax 

In WebSphere V3, JSP conforms to the JavaServer Pages Specifications 
0.91 or 1.0 from Sun Microsystems. IBM has added some enhancements 
particularly in the area of database access. The Sun JSP 1.0 specification 
can be found at 

http://java.sun.coni/protfcicts/jsp/download.html 

A full discussion of JSP syntax including the differences between Version 
0.91 and 1.0, and details of the IBM extensions can be found in the redbook 
WebSphere Studio and VisualAge for Java Servlet and JSP Proorammina 
SG24-5755-00 *' 



1.5 Enterprise Java Server (EJS) Runtime 

The Enterprise Java Server (EJS) Runtime provides support for the 
Enterprise Java beans (EJB) programming model in which enterprise beans 
are managed by containers. Containers, in turn are executed within servers 
which are operating system processes that contain their own Java Virtual 
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Machine (JVM). Each JVM is managed by the System Management 
infrastructure of the application server. 



The SM infrastructure allows the execution environment to be defined, 
enabled and monitored. The execution environment is made up of beans 
containers and servers. 

For more detailed descriptions and examples on each of the EJS functions 
please refer to 2.1 , "IBM WebSphere Application Server components" on 
page 31 . 

1.5.1 Enhancements to the IBM extensions required for the EJS 

The EJS programing model utilizes the RMI/IIOP model to provide distribution 
for the EJBs in standard and advanced releases of the EJS. The enterprise 
release of EJS requires the use of Interface Definition Language (IDL) to 
allow interoperability with the Component Broker (CB). 

Some of the existing IBM extensions in the IBM Java ORB have been 
re-implemented as an effort by the Component Broker team to enhance the 
JBroker Java ORB to support the EJS. Some of these features are briefly 
discussed below. 

1.5.1.1 Persistent Name Service (PNS) 

PNS is not an ORB feature but it is required to provide reference to the 
persistent objects. PNS implements CORBA CosNaming specification and 
this mechanism will be standardized for pluggable persistence. 

1.5.1.2 Object Resolver 

The Object Resolver provides a pluggable interface to allow an external class 
to act as a specialized object adapter. 

1.5.1.3 Request Interceptor (Rl) 

The Rl allows access to the request header after marshalling out and before 
demarshalling in. This was done because the Request and Message 
Interceptor design from the original Sun ORB was not compatible with how 
C++ ORB handled interceptors. 

1.5.1.4 Property setting and getting flags 

Since the OMG defines only a couple of basic properties 

(org.orag.OORBA.GRBdass, org . omg . CDRBA . ORBS ingletonClass) , they are not 

enough for IBM-specific properties. Support for these properties has been 
added and it will affect the method oRB.setjparameters and other affiliated 
methods. 
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1.5.1.5 JNDI support 

EJS implements the Java JNDI APIs to support the CORBA CosNaming. 

1.5.1.6 Java Transaction Service (JTS) 

JTS supports the ORB. This is done by implementing the Request 
Interceptors, which allows the JTS to be enabled by the ORB. 

1.5.1.7 Browser callbacks 

Normally, a client makes method calls to an object residing on the server. 
This is done when the server creates a listener socket and the client opens a 
port to that socket. By using the same listener socket, created by the server, 
and the port, opened by the client, functionality has been added for the server 
to make method calls to the object residing in the client. The roles have been 
essentially reversed. This is possible only in the case of signed applets. A 
similar capability has been added to the C++ ORB. 

1.5.2 New features in Java ORB required for the EJS 

Some of the new features in the IBM Java ORB, that are required by the EJS 
runtime have been briefly discussed below. 

1.5.2.1 Pluggable feature framework 

In WebSphere V3.0, special emphasis has been paid to providing a very 
pluggable component-based framework. This kind of framework will take care 
of problems arising from receiving frequent updates of the Java ORB from 
Sun Microsystems and it will meet the needs of different internal customers 
with varying requirements. This feature is meant for private use only by the 
ORB team 

1.5.2.2 Pluggable transport layer 

In order to support any environment, it is necessary to have a pluggable 
transport layer. EJS has a pluggable transport layer, which means that the 
socket creation will have to take place in this layer. Other ramifications are 
that the CDRInputStream and CDROutputStream will also have to be 
replaceable. 

1.5.2.3 SSL support 

Support for the SSL interface on the server side has been provided. Using the 
MIME encoded MOP allows browsers and Web servers to use SSL By 
selecting to enable SSL, the user can force an SSL connection between the 
client and Web server for greater protection of the user ID and password data. 
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1.5.2.4 Mime-encoded HOP tunneling with HTTP 

HOP tunneling means sending IIOP messages embedded in an HTTP 
request/response. When the client or a firewall does not allow a post method 
to nmme encoded IIOP tunneling technique can be used. This technZe ' 
anows the mimeencoded IIOP to tunnel through an HTTP firewall or Web 
server as an HTTP message. 




Figure 10. Mime encoded IIOP tunneling through a 3-tier framework 
1.5.2.5 IIOP tunneling 

There are 2 types of IIOP tunneling. In the first approach, multiple IIOP 
messages are embedded in an HTTP request and are communicated to the 
ORB using sockets. This approach has some security implications on Web 
servers and will not be used. The second approach is to attach the IIOP 
request to a single HTTP request as a parameter with binary data. This 
request reaches the ORB using the servlet that is started by the HTTP 
request. The response is then sent back as binary IIOP data. This approach 
is used since it is more secure. 
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1.5.2.6 HOP firewall support 

SOCKS V5 is used to provide the HOP firewall support by providina 
authenticated connections. 

1.5.2.7 HOP red i rector 

HOP redirector works in a similar fashion to the proxy firewall. It copies any 
replies/requests on a socket to a socket on which the ORB is connected. 

1.5.2.8 Configurable requests time-outs 

Only client-side timeouts have been implemented. This is done by throwing 
the NCLRESPONSE system exception on the client side with the completion 
status of maybe. The timeouts are set by using two ORB properties: 

1. com.ibm.CORBA.RequestTimeout 

2. com.ibm.CORBA.LocateRequestTimeout 

The default value for both of these timeouts is 0. A timeout value of 0 means 
an infinite timeout interval. 

1.5.2.9 eNetwork Dispatcher 

The eNetwork Dispatcher is a WebSphere HTTP sprayer used from Work 
Load Management (WLM). 

1.5.2.10 LDAP naming service 

EJS provides the LDAP naming service support indirectly through a JDBC 
layer implemented for CosNaming. As part of LDAP support, the EJS also 
supports the URL context. 

1.5.2.11 Work Load Management support (WLM) 

WLM distributes the workload or requests across a server group. This 
functionality is supported in WebSphere V3. Smart proxies are used within 
the client along with a WLM runtime. 



1.6 Preparing for Installation - What to change and why 

Before running the setup of WebSphere for version 3.0 it was necessary to 
make some of the following changes, to ensure a good install. These hints 
were documented in the WebSphere Readme file that shipped with the 
product 



24 



Application Server Solution Guide Enterprise Edition: Getting Started 



1-6.1 Set the JAVA_HOME environment variable 

Setting this variable allowed the OLT install to find the correct files as 
discussed in 4.3.0.2, -Installing and configuring the OLT/OLD environment" 
on page 268. The 3.02 WebSphere install on NT completes successfully eve 
if the java_home variable is not set. 

For the Windows NT platform: 

1 . Open the Control Panel. 

2. Double click the System icon. 

3. Select the Environment tab. 




Figure 1 1. The Windows NT System Properties Environment settings 

4. Type in JAVA_HOME in the variable field. 

5. Type in your JDK path, for example C:\jdki.i. tb in the value field. 

6. Click Set. 

7. Click OK. 
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For the AIX Platform: 

1 . Log in as root or a super user. 

2. cd/etc 

3. Edit the environment file with an editor of choice, for example, vi. 

4. Add the line JAVAJiOME-/usr/ j dk_base. 

5. Save the file and exit. Next time you log in the environment will be 
updated. Below is an example of our settings within the /etc/environment 



HOfr/usr/hin: /etc : /usr/sbin : /usr/ucb : /usr/bin/Xll : /sbin 
IANG=en_US 

IOCPA1H=/usr/lib/nls/loc 

^ P ^^ r/I ^ /r ^ 8/ras 9 /%L/%N: / usr / li±> / nls /"Kg/*L/%N. cat 

# GDK routines use OCMDIR to determine which objects to operate on 
I ^.^ f ^ t G /^/^repos - this is where the device Objects 
preside, which are required for hardware configuration 
CCMDHU/etc/objrepos 

# IMNSearch DBCS environment variables 
IMQGCNFIGSRV=/etc/lMNSearch 
IMQCXMFIGCX=/etc/IMNSearch/dbcshelp 

# Added by Steen 
JAVA_HCMB=t/usr/ j dk_base 

IX> LIBRARy PA3H=/usr/ j dk base/lib/ aix/ native threads : /usr/Web^here/AppServer/ol 
ugins/aix : /home/dh2 instl/sqlliJp/ lib : /usr/lib~ m^pnere/Appyerver/pl 



Figure 12. /etc/environment settings 



.2 Increase the DB2 application heap size for the WAS database 

In order for the Admin Server to work correctly the application heap size must 
be changed from its default setting of 128 to a new value of 256. In the 3.02 
install on NT the installation will update this setting automatically for you This 
can be done manually either through the DB2 UDB Control Center or through 
the db2 command line interface, below are examples of both. 

From the DB2 UDB Control Center: 

1 . Open the Control Center and expand the system that the WAS Database 
resides on, so you can see the WAS DB on your screen, as shown below 
in Figure 13 on page 27- 
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S-& WTR05083 
B 0j Instances 
B-II3 DB2 

& ^ Databases 

m- 0 SAMPU 



F/gure 13. 082 l/DB Control Center - the WAS database 

2. Right-click the WAS database icon and select Configure. 



Chapter 1 . WebSphere applications 27 




Figure 14. Configure the WAS database 



3. Select the Performance tab. 

4. Scroti down the list of parameters and select Application heap size. 

5. Change the value from 128 to 256. 
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Figure 15. How to change the application heap size 

6. Click OK. 

7. Close the Control Center. 
From the command line: 

1. Start up a DB2 Command Line window (NT) or ensure your 
~/sqllib/db2profile has been activated (AIX). 

2. Connect to the WAS database with a valid user ID and password: 
connect to was 

3. To update, type the following command: 

update db cfg for was using APPLHEAPSZ 256 

4. Disconnect all applications: 

force applications all 
terminate 

5. Then stop and start db2. 
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Chapter 2. WebSphere Application Server overview 



This chapter will give a high-level overview of the Enterprise Java Server 
functions as deployed in IBM WebSphere V 3.0. 



2.1 IBM WebSphere Application Server components ~ 

WebSphere Enterprise edition ships with two different Enterprise Java 
Servers as discussed in 1.3.2, "EJB architecture in brier on page 12 The 
following is an overview of the main components in the EJS provided by 
WebSphere Advanced Edition (AE) and a brief look at the main components 
° A f 1 I provided b * Component Broker (CB). We also discuss the features 
of WebSphere Standard Edition because they are included in Advanced 
Edition and they provide the necessary foundation for Advanced Edition 
functions. 

2.1.1 Architecture overview 

This section gives an overview of the components in the general EJS 
architecture. 

Enterprise Java Services (EJS) refers to the infrastructure designed to run 
servlets and Enterprise Java beans. 

The EJS is based on Sun's Enterprise JavaBeans Technology specifications 
that specify an enterprise Java platform defined through a set of standard 
Java APIs that provide access to existing infrastructure services. 

2.1.1.1 EJS architecture 

An EJB server provides the following components: 

• The EJB server runtime 

The server runtime can be seen as a generic server (or model/template 
server) from which the Web application server instances can be modeled. 
EJBs live in containers that again live in the server runtime (Web 
application server) see Figure 18 on page 37. 

Servlets also live in a special container (servlet engine) that again live in 
the server runtime (Web application server) see Figure 17 on page 36. 

• The EJB containers 

EJB containers are provided following the requirements as described in 
the Enterprise JavaBeans specifications Version 1 .0 (for further 
information see http://java.sun.com/products/ejb/). Furthermore, IBM 
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provides additional features for example, entity bean support with bean 
managed or container managed persistency and a simple deployment 
tool. 

See 2.1.2, "Enterprise Java beans and containers" on page 39 for more 
details on containers and EJBs. 

• The Enterprise Java beans 

This combination of components provides a number of services. These are: 

• A deployment tool 

When an EJB has been developed it has to be transformed into a form that 
enables it to be managed and accessed. The transformation is referred to 
as EJB deployment. 

To deploy an EJB you will normally use a built-in tool of an IDE (Integrated 
Development Environment) or a stand alone tool. 

See 2.1.4, "Deployment tools" on page 40 for more details. 

• Naming services 

The IBM WebSphere Application server architecture provides naming and 
directory services to provide an interface to find EJBs based on the name 
or an attached attribute. 

In IBM WebSphere the Java Naming and Directory Interface (JNDI) is 
used to provide a common interface to the actual naming and directory 
service that is being used. 

JNDI provides an Application Program Interface (API) to be accessed 
through a Java application and a Service Provider Interface (SPI) to 
specify the interface to existing and widely used name and/or directory 
services. The purpose of providing an open SPI specification is to make 
the JNDI independent of the specific naming or directory service 
implementation used. 

For further information on the JNDI specifications see: 

http : / / j ava . sun . com/ products/ jndi/ 

For more details on naming and directory services see Chapter 7, 
"WebSphere access control and security* on page 363. 

• Security services 

The security services provide support for Web resources (for example, 
HTML, JSP and CGI files), servlets and EJBs. 

The security authorization information, authentication and delegation 
policies will typically be defined using the IBM WebSphere Administrative 
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Console. In WebSphere Advanced the security service is an EJB server 
that contains security beans. 

See Chapter 7, "WebSphere access control and security* on page 363 for 
more details on security. 

• Work Load Management 

A Work load management (WLM) mechanism is provided to make scaling 
of enterprise applications running on IBM WebSphere Application server 
possible. 

Workload Management is a service that improves the scalability of an EJB 
server runtime environment by grouping multiple servers together into a 
server group. EJB clients can access this server group as if it was a single 
server. The actual server that responds to the client request will be 
transparently determined by the Workload Management service. 
WebSphere implements a number of different policies for how the 
Workload Management service will choose the server. 

We do not cover Workload Management in this book. 

• A persistence service 

This service provides support for the proper interaction between a bean 
and its data source to ensure that any persistent data is maintained. 

In AE this is accomplished by using the JDBC API to interface with 
relational databases and Java transaction support. 

In CB the persistent service is accomplished using the X/Open XA 
interface to relational databases and the OMG Object Transaction service. 

• A transaction service 

This service implements the transactional attributes specified in an EJB's 
deployment descriptor. 

► System management infrastructure 

The system management infrastructure enables management of Web 
server, Web application server and Web application resources. A client 
interface is provided for the administrator to manage these resources. 

An overview of the AE system management infrastructure is given in 2.1 .5, 
"System Management Infrastructure" on page 40. 

The IBM WebSphere Administrative Console is provided with IBM 
WebSphere 3.0 Advanced. 

See 2.1.5.1, "Systems management console" on page 41. 
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The client interface for the EJB server (CB) environment is the systems 
management end user interface. We do not discuss this interface in this 
redbook. Please refer to the redbook WebSphere Application Server 
Enterprise Edition Component Broker 3.0 First Steps, SG242033 for more 
details. 



2.1.1.2 WebSphere Application Server Standard Edition 

The WebSphere Application Server Standard Edition provides a basic Web 
application server environment for Web applications that typically consist of 
HTML files, JSP files, applets, servlets, image files and databases. 

The primary purpose of the IBM WebSphere Application Servers is to provide 
an environment into which scalable, portable, well performing and reliable 
Web applications can be developed and executed based on Java-based 
programming, standard techniques, Internet standards, standard middleware 
and database management systems. 

IBM WebSphere Application Server Standard Edition provides an 
environment where you can extend and enhance your Web applications by 
migrating your HTML to JSP. Since JSPs essentially are HTML files with 
additional JSP-specific tags you can use your HTML skills and standard 
development tools. 

IBM WebSphere Application Server compiles the JSPs (at runtime) and 
transfers them into servlets. However, this process is managed by IBM 
WebSphere Application Server and is transparent to the developer. 

Since JSPs can include Java code and you write your servlets in Java you 
can use Java in your development - if you want to or the requirements force 
you to. However, you are not necessarily required to do so. 

Traditional" Web development components like CGI programs, Web Server 
APIs and client side scripting languages may also be utilized since an IBM 
Web Application Server setup includes a 'traditional" Web server. 

IBM WebSphere Application Server Version 3 integrates with many different 
Web Servers and includes plug-ins for IBM HTTP Server, Apache, Lotus 
Domino Go V4.6.2.5, Lotus Domino, Netscape Enterprise Server, and 
Microsoft IIS. 

To integrate with a Web server you must select one or more of the plug-in 
extensions as shown in Figure 16 on page 35. 
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Figure 16. Web servers that integrate with the application server 



The application server provides the runtime environment for execution of 
servlets. See Figure 17 on page 36 for a view of this runtime architecture. 

The Web application server also provides a connection manager function that 
manages database connections. The connection manager provides an easy 
to use mechanism for reducing the resources required by Web applications 
when accessing databases. 

Furthermore, the Web application server provides transaction support 
through an implementation of Java Transaction Server (JTS) in relation with 
JDBC/XA databases. 

Finally, the IBM WebSphere Application Server Standard Edition architecture 
includes a system management infrastructure with two primary components 
the Administrative server and the Administrative client (console) (seeFigure 
17 on page 36). 

For further information on the system management structure see 2.1.5, 
"System Management Infrastructure" on page 40. 
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Figure 17. WebSphere Application Server Standard Edition 3.0 runtime architecture 



2.1.1.3 WebSphere Application Server Advanced Edition 

The WebSphere Application Server Advanced Edition (AE) has the functions 
found in the WebSphere Application Server Standard Edition plus support for 
EJBs and distributed (clustered) systems. This application server is one of 
two EJB servers provided in IBM WebSphere Enterprise Edition. 

Since IBM WebSphere Application Server Advanced Edition is an extension 
of the Standard Edition you can easily move an application developed for a 
server running Standard Edition to servers running Advanced Edition. 

The Web application server in IBM WebSphere Application Server Advanced 
Edition (see Figure 18 on page 37) includes support for EJB containers (for 
the EJBs) besides the servlet engine (for the servlets and JSPs) also found in 
Standard Edition. 
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Figure 18. WebSphere Application Server Advanced Edition 3.0 runtime architecture 

There is a single instance of the administrative server on a single node 
(physical machine). 



In a multi-node setup (cell) there will be a single instance of the administrative 
server on each node. The administrative servers contains identical 
configuration information and access the same configuration repository in the 
same database (see Figure 19 on page 38). 

The rationale is that you should be able to access any one of the 
administrative servers in a cell and see changes reflected on any other 
administrative server in the cell (single administrative image). 

The WebSphere administrative database can be located either on a separate 
database server (physical machine) or on one of the machines that host the 
administrative servers. However, each machine must have database server, 
client or connection software installed and configured to enable access to the 
common database. 
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If you plan to run the same Web applications and enterprise applications on 
more than one physical machine you will also have to ensure that all systems 
have access to identical (or the same) files and in identical locations in the 
directory structures. This can be accomplished either by creating identical 
files and directory structures on each machine or by using a shared file 
system. If the first method is used we would recommend that you establish an 
automatic or semi-automatic procedure to ensure that the data are identical. 



Node 2 




Figure 19. WebSphere Application Server Advanced Edition multi-node setup 

A concept of server groups has been implemented in the IBM WebSphere 
Application Server for management and control purposes. 

The following applies to the server group concept: 

• Server groups consist of one or more Web application servers. 

• A single Web application server can only belong to one server group. 

• A server group can be seen as a logical server. 

• Web application servers within a group are clones of each other. Clones in 
this context means logically identical application servers with respect to 
configuration of resources for example, containers and EJBs. 
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The Web application servers within a server group may be distributed to 
different nodes (physical machines). 



The server group is very useful in relation to workload management A 
request can be forwarded to a server group and the request is handled by a 
server in the group while the specific server identity is hidden from the 
requester. 

2.1.2 Enterprise Java beans and containers 

The IBM WebSphere Application Server Version 3.0 server architecture 
provides a generic server (the Web application server, see Figure 18 on page 
37) in which EJB containers live. 

One of the primary responsibilities of an EJB container is to provide a number 
of fundamental services for example, transaction, state, security and 
persistence to the EJB. The advantage being that it reduces the work 
required by the EJB developers and supports development of portable EJBs. 

Another responsibility of an EJB container is to create the interfaces (EJB 
Home and EJB Object) required for an EJB client to access a deployed EJB 
so the EJB client interacts indirectly with the EJB through the EJB container. 




Figure 20. Client ~ EJB container relationship 



2.1.3 Servlets and the application server 

A special container (a servlet engine) is provided in IBM WebSphere 
Application Server to enable servlets to be run within the application server. 
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The servlet engine has been designed to be integrated as seamlessly as 
possible in the EJS architecture as well as in the security and system 
management infrastructure. The design approach allows for consistent 
system management for servlets and EJBs as appropriate while maintaining 
tne typical servlet environment and characteristics intact. 

Servlets are created and managed as members of a Web application in IBM 
WebSphere Application Server Version 3.0. IBM WebSphere Application 
Server provides work load management support for servlets (as it does for 
EJBs) to allow requests for servlets within a server group to be distributed to 
application servers belonging to the group. 

2.1.4 Deployment tools 

When you have developed your Enterprise Java beans for example, using 
VisualAge for Java or manually, they have to be deployed. 

When you deploy an EJB you create or modify a Jar file which includes a 
description of the Jar file contents (the manifest), deployment descriptors, 
bean class files and potentially environment properties. 

To create a deployed EJB Jar file you can for example, use VisualAge for 
Java, the Jetace tool or you can use the tools available in the Java 
Development Kit (JDK). The Jetace tool is provided as part of the IBM 
WebSphere Application Server. 

After the EJB Jar file has been deployed for your IBM WebSphere Application 
Server it must be installed in your environment in accordance with the 
WebSphere administrative infrastructure. IBM WebSphere Application Server 
Advanced Edition provides the WebSphere Advanced Administrative Console 
to be used for EJB creation (installation). 

Depending on the requirements for your EJB you may even choose to deploy 
an undeployed Jar file during EJB creation using the WebSphere Advanced 
Administrative Console. 

You will also find a command line tool wlmjar with WebSphere Application 
Server Advanced Edition that can be used to create a workload-managed 
prepared version of your Jar file. 

2.1.5 System Management Infrastructure 

This section describes the IBM WebSphere Application Server administration 
model. 
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2.1.5.1 Systems management console 

The WebSphere Administrative Console is the system management console 
for IBM WebSphere Application Server Version 3.0 Advanced Edition. 

An administrative domain (sometimes referred to as a cell or sphere,) is a 
collection of managed nodes, that is, host machines. Each managed node 
has an administration server executing on that node that is responsible for 
configuring, monitoring, and managing the WebSphere servers that run on 
that node. A client graphical user interface is provided to enable the 
administrative domain to be defined. 




Administrative Entity Be an HP 

c * ien * Session Bean^^ 



Servfet i > 

Figure 21. WebSphere Administration Server administration model 



This Graphical User Interface (GUI) makes it easy to interact with the beans 
that were loaded by the adminserver. The front-end has a tab look and feel 
and has three main tabs as shown in Figure 22 on page 42, Figure 23 on 
page 43, and Figure 24 on page 45. The WebSphere Administrative Console 
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has three tab panes namely Types, Topology, and Tasks. These three panes 
are discussed below. 



2.1.6 The Types view 

The Types view is a hierarchical view of all resources on all nodes in the 
administrative domain. Each folder icon represents a different resource type. 
By selecting any object and right clicking, a context-sensitive menu appears. 
This menu has the basic tasks such as Create, Move, Default Properties. 

The Types pane is shown in Figure 22 on page 42. 




| 3/28/00 4:48 PB : Loading ... 
\ 3/28/00 4:48 PH : Console Read?. 




Figure 22. WebSphere Advanced Administrative Console - Types tab 

2.1.7 The Topology view 

The Topology pane consists of the WebSphere Administrative Domain and all 
the managed nodes as shown in Figure 23 on page 43. For each managed 
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node there is an associated hierarchy of all the resources within that node. 
The resource attributes can be changed and methods can be invoked on 
these resources in this view also, just as in the Types view. 



WebSphere Advanced AdminisOative Console 
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Fjgi/re 23. WebSphere Advanced Administrative Console - Topology tab 
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2.1.8 The Tasks view 

The Tasks view shows different tasks that can be performed and is shown in 
Figure 24 on page 45. It consists of three task groups, which are briefly 
discussed below. 

2.1.8.1 Configuration tasks 

This group of tasks allows you to configure application servers, virtual hosts, 
servlet engines, web Applications, and enterprise applications. 

2.1.8.2 Performance tasks 

This task allows the user to launch the Resource Analyzer tool to monitor 
performance and load statistics. The Resource Analzer is dicussed in more 
detail in the redbook WebSphere V3 Performance Tuning Guide 
SG24-5657-00. 

2.1.8.3 Security tasks 

Using this task, you can apply security to enterprise applications and to the 
HTTP and EJB methods of resources such as servlets and enterprise beans. 
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Figure 24, WebSphere Advanced Administrative Console - Tasks tab 
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8.1.6 Starting the LDAP directory server from the command line 

To start LDAP from the command line you should use the following command: 

/usr/ldap/bin/slapd 

8.1.7 Administration interface - Web 



From the Directory Server Web Admin you can perform several administrative 
task such as: 

• Configure a database 

• Configure a replica 

• Start up and shut down the server 

• Define an ACL 

• Add and delete suffixes 

• Add entries to the directory 

To use the Directory Web Admin you have to start up a Web browser and type 
in the Location field http://hostarroe/id£¥L 




D Introduction 
BLAgm 



<3 Ready 

IBM SecnreWay Directory Server Administration ISM* 




Please enter a dbtmguished LDAP user : 
Logon. 



and password and cHck 



User ID: [ 



M Cnptm^IgM Cmrcflrtmn 1998 All rirfiU mttmd. 




Figure 405. Idap Web admin 
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For the user ID specify cn=root or the user that you specified in the 
administrator DN and password section in Figure 401 on page 413. 

For the password type the password that you specified in the administrator 
ON and password section and click the Logon button. 

8.1.8 DMT interface 

Use the DMT tool to: 

• Connect to one or more directory servers via SSL or non-SSL 
connections. 

• Display server properties and rebind to the server. 

• List, add, edit, and delete schema attributes and object classes. 

• List, add, edit, and delete directory entries. 

• Modify directory entry ACLs. 

• Search the directory tree. 

You can configure the tool to automatically connect to one or more servers 
and to log in particular Distinguished Names (DNs) when it is started. To 
configure the tool, edit the /usr/ldap/etc/dmt.conf DMT configuration file. For 
example, the property file contains these lines: 

• server1.url=ldap://loca!host:389 

• server! .security.bindDN= 

• served .security.password= 

• served .security.ssl.keyclass= 

8.1.8.1 Log on to a server 

If a directory user DN and password are not provided in the DMT 
configuration file, the tool connects as an anonymous user when it is started. 
Although an anonymous user can browse the directory tree and schema, to 
perform directory updates, in most instances, you need to log on as a 
directory user. To modify the directory server schema you must log on as the 
server administrator. To log on as a different user: 

1. Click Server -> Rebind. 

2. Provide the user DN and password. 

3. Press Enter. 

To start the DMT tool enter drat &. 
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Figure 40$. DMT 

For more information about how to use this tool, see: 

http: //www-4 . itcn. com/eof tware/netvork/directory/ 

8.1.9 Configuration files - attributes and objects classes 

The file /etc/slapd.conf contains configuration properties such as the SSL 
port, DB2 user, admin DIM, and the admin password. 



adtriuFW 

>14II90naWtK3^IEK+<3^ 
M4VjZxR*/jFrjBV0b7^^ 
adroinTN °crt=root" 

# IBM SecureW&y Directory Server Configuration File V3.1.1 far AIX 

# CWTTICN: EDIT THIS FILE WITH CWcB 

# We xeuu a im ri risking all ^*^gp« through the server adnunistraticn interface. 
sysLogLevelra 
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exzorLog/tnp/ slapd . errors 
includeScheraa /etc/l(Jap6chema/V3 . system, at 
includeScfaeRB /etc/lcfapschema/V3 . ihm. at 
includeScherna /etc/ldapscheraa/V3 .user, at 
iucludeSctoB /etc/ldapecdaeraa/V3 . system, oc 
includeScherna /etc/ldapscherra/V3 . ibm. oc 
iacludeSchema /etc/ldapschena/V3 .user . oc 
iacludeSchema /etc/ldapscheraa/V3 .ldapcyntaxes 
iacludeSchema /etc/ldapechema/V3 .matrhingrules 

# The next file is for schema changes. It's empty when the package is installed 
includeScbema /etc/ldapschema/V3 .modif iedscheroa 

scheraacheck V3_lenieot 
port389 
secureBotrt£36 
securityiODe 

#sslAuth options: serverauth/server cl ipntau th 

sslAuth eerverauth 

sslOertificate none 

sslCipherSpecs 12288 

sslKeyRingFile key.kdb 

sslKeyRinc^ileHtene 

rnaxthreads250 

waitijngthreads 75 

ffTTm nar^THI ^fTnrmPr^innR on 

tineliinitduO 
sizelimitSOO 

#p*encryption options: iitBsk/none/cryFt/SHA 
pwencryption iraask. 

fl»HflflHHHWfffl»flH linffffOfffl M H» ff MWWnM 0 H»»f>M HlfffWrfM fl f I W H H f I fill fl fl f f f f f > H »ff»H f fnff ffff flffff ff flH 

# Trfr^ HafahacP definitions 

n« finiffiff »nwfiniii#JfnH nwinifMffi » fjiifinfJH»»o ffM Mff» >r»M »»»»»» tifinff frnwfiHiiwHfnf »fifiHff» »«w 

database Irtrf 
suffix "cn=scheraa w 

flgffffffnffWfififfM unrrn H»firiH»fffffifni n»fnj»rinirfiHfffriiH»»nHnrifffi»ri«Hrjfni » rfrmfffinHfinfrn n »n 

# rdbra database definitions 

iiiiwofitinff nnn fin» Hnnrtff wnnriff rifiw tiiJtifiHff Hff rifffifffiririrt fninuw nnri HfiHf i n wrifififf u nff» n r rtifuf n 



plugin Hafaha^ /lib/libback-rdbrii. a rctaajaackendjlnit 

suffix c«IEM, c=OS" 
&tabaselfcneLdapci& 

dbusexpif 

4^^XXy*^WHiyO?/^l r ■"'wrm.Lgx jjju i * ~ it mm i j t mtfm » vn ii ii| i " — — — — z * 

dbuseridLdapdb2 

suffix "cn=localhost" 
readOolyjff 

# point this path at your changelog conf file and unconment 

# (it must be full path) 
#ioclude /etc/ldapschena/slapd.cl.aonf 



If you want to add a new object, modify or delete classes or attributes you can 
use the DMT tool. This tool also lets you know how the standard object 
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classes are created. Any attribute or class modification dynamically changes 
the directory schema. 

To add an object click Schema -> Object Classes -> Add Object class. 

To add an attribute click Schema -> Attributes -> Add attribute. 
For further information see the SecureWay Directory Web site at: 

http: //wwv-4 . ihm. com/ software/network/directory/ . 

8.1.10 LDAP commands 

We now show you how to use some of the more important LDAP commands 
from the user's point of view. There are more specific IBM SecureWay LDAP 
commands for administrative purposes. Other vendors who have 
implemented these commands may be using different flags. 

8.1.10.1 LDIF format 

LDAP Data Interchange Format (LDIF) is a format for representing LDAP 
entries in text form. It is widely used and accepted as a de-facto standard. 
LDIF is used by the Idapmodify, Idapadd, and Idapsearch command-line 
utilities. The basic form for an entry in an LDIF file is as follows: 

• dn: distinguished name> 

• objectClass: <object class> 

• objectClass: <object class> 

• <attrtype>: <attrvalue 

• <attrtyp^>: <attrvalue> 

An LDIF file consists of a series of records separated by a blank line. A record 
is a directory entry with a mandatory DN and at least an objectClass if the 
record is a new entry. If the record is for an update only, the DN is required. 
Some attributes, required by an objectClass, must be defined. Attribute 
values can be clear text, such as a name, or they can be Base64 encoded 
binary data, such as for a JPEG picture. 

8.1.10.2 The Idapmodify and Idapadd utilities 

The Idapmodify utility is a command-line utility built around the ldap_modify() 
API. The utility opens a connection to an LDAP server, binds to the server, 
and modifies an entry. The entry information is read from standard input or 
from a file. The Idapadd utility is implemented as a renamed version of 
Idapmodify. The Idapadd works the same way as the idapmodify with the -a 
flag set. The syntax of the utility is: 
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ldapraodify [options] [-f <ldif input file>] 
ldapadd [options] [-f <ldif input f ile>) 

Some options are: 

• -h host LDAP server host name 

• -p port LDAP server port number, default 389 

• -D dnbind dn by default anonymous 

• -w bind password 

• -R specifies that referrals are not to be automatically followed 

• -M manage referral objects as normal entries 

• -V LDAP protocol version (2 or 3; default is 3) 

• -C charset character set name to use, as registered with 

IANA 

• -b Assumes that any values that start with a / are binary values, and that 

the actual value is in a file whose path is specified in the 
place where values normally appear 

• -c continuous operation; do not stop processing on error 

• -n show what would be done but don't actually do it 

• -v verbose mode 

• -d level set debug level in LDAP library 

Examples 

Following are some examples using the LDAP commands: 

ldapadd -h rs600030 -D "cn^root* -w swall7r -f add.ldif 

This is the add.ldif's contents: 



cn=*farisa,CRi=TIS3,c^iJ3n / c=us 

so=cicsMan 

cbjectclass==ePerBoa 

cbjectcIass=perBcn 

dbj ectxiasB=inetDrgfPerscti 

cbjectxlass=top 

cbj ectclass=ca?ganizatJ.analPer8ari 
uixfcttxdsa 

ttaiksMarisaQar . itora. ocro 
cn^Marisa 

userPasswctrd=swall7r 
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Now let's modify the Marisa's mail attribute: 

ldapmodify -h rs600030 -D *cn=root w -w swail7r -d mod.ldif 



at^fcrisa , ousTISO , o*Ubrn, c=*ts 

obj ectclass=ePerBcn 

obj ectclasB=persoii 

cbj ectclass =inetOtrgPersaa 

cbjectclase=top 

obj ectclass =<arganizatianalfferson . 
nail=cic^bnfiar . iJaa. com 



To validate the change we ran the Idapsearch command: 

ldapsearch -h rs600030 -b "ou=ITSO,o=IBM,c=US n cn=Marisa 



cn*=*ferisa , ou^aCTSO , o=Ubra , c=us 



uid=Marisa 
co=ffarisa 

cbjectciass=ePerBcti 

obj ectclass =fric; i.' 

dbj ectclass =lnet3Q[EgR^L qua 

cbjectclas8=tcp 

cbj ectclass= ui9^> ij ra tional Person 
raaU^cics>tenflar . ibm. com 



8.1.10.3 The Idapsearch utility 

The idapsearch utility is a command-line utility built around the 
ldap_search() API. The utility opens a connection to an LDAP server, binds to 
the server, and performs a search using a specified search filter. If the 
request finds one or more entries, the requested attributes are retrieved, and 
the entries and values are printed to standard output. If no attributes are 
specified, all attributes associated with each returned entry are displayed. 
The syntax is: 

Idapsearch [options] filter [attributes] 

The significant parameter options for the Idapsearch tool are: 

• -h LDAP server host name 

• -p LDAP server port number 

• -D bind dn 

• -w bind password 

• -b base dn for search; LDAP_BASEDN in environment is default 

• -s search scope (base, one, or sub) 
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• -a how to reference aliases (never, always, search, or find) 

• -I time limit (in seconds) for search 

• -z size limit (in entries) for search 

• -f perform sequence of searches using filters in file 

• -A retrieve attribute names only (no values) 

• -R do not automatically chase referrals 

• -M manage referral objects as normal entries 

• -V LDAP protocol version (2 or 3; default is 3) 

• -C character set name to use, as registered with IANA 

• -B do not suppress printing of non-ASCII values 

• -L print entries in LDIF format (-B is implied) 

• -F print separation between attribute names and values 

• -t write values to files in /tmp 

• -n show what would be done but don't actually do it 

• -v run in verbose mode 

• -d set debug level to level in LDAP library 

The search filter, in many cases, will either be a simple attribute search (such 
as cn=Smith) or for all attributes (cn=*). Search filters, however, can be fairly 
complex, and there is a separate RFC (RFC 2254) that you should refer to if 
you need all the details. The following is a brief description of search filters. A 
search filter defines criteria that an entry must match to be returned from a 
search. The basic component of a search filter is an attribute value assertion 
of the form: 

attribute operator value 

For example, to search for a person named John Smith, the search filter 
would be cn^John Smith. In this case, cn is the attribute, = is the operator, 
and John Smith is the value. This search filter matches entries with the 
common name John Smith. Table 9 on page 4241 ists the operators for search 
filters. 



Chapter 8. Directory Services 



423 



Table 9. Operators 



Operator 


Description 


Example 




Returns entries whose attribute is 
equal to the value. 


cn=John Smith finds the 
entry with the common 
name John Smith. 


>= 


Returns entries whose attribute is 
greater than or equal to the value. 


sn>=smith finds all entries 
from smith to z\ 


<= 


Returns entries whose attribute is 
less than or equal to the value. 


sn<=smith finds all entries 
from a* to smith. 




Returns entries that have a value 
set for that attribute. 


sn=* finds all entries that 
have the sn attribute. 




Returns entries whose attribute 
value approximately matches the 
specified value. Typically, this is 
an algorithm that matches words 
that sound alike. 


sn~= smit might find the 
entry M sn=smith". 



The **" character matches any substring and can be used with the = operator. 
For example, cn=J*Smi* would match John Smith and Jan Smitty. Search 
filters can be combined with Boolean operators to form more complex search 
filters. The syntax for combining search filters is: 

( or T (filterl) (filter2) (filter3) ...) 

(■!■ (filter)) 

The Boolean operators are listed in the following table: 



Table 10. Operators 



Boolean operator 


Description 


& 


Returns entries matching all specified filter 
criteria. 


I 


Returns entries matching one or more of 
the filter criteria. 


I 


Returns entries for which the filter is not 
true. This operator can only be applied to 
a single filter. ( ! (filter) ) is valid, 
but { 1 (f ilterl) (f ilter2) ) is 
not. 
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Examples: 

1. Retrieve all the entries with a person object defined; 

ldapsearch -h rs6 00030 -b "o=IBM,c=US n obj ectclass=person 

2. Retrieve all the entries with an e-mail ending in "ibm.com"; 

ldapsearch -h rs600030 -b fl o=IBM,c=US n mail=*ibm.com 

3. Retrieve all the entries with cn=Marina and mail=*ibm.com; 

ldapsearch -h rs600030 -b "o=IBM,c=US n 
n (& (cn==Marisa) (mail=*ibra. com) ) " 

Note that we used " 0 in the filter. The reason was that on AIX the ksh 
preprocesses the () directive with 0 ° and doesn't preprocess the 
contents. 

4. Retrieve all entries with mail=*ibm.com and cn not equal to Karina, root; 

ldapsearch -h rs6 00030 -b "o=IBM,c=U5" 

tt (&(mail=*ibm.com) (1 ( | (cn=Karina) (cn=rcot) ) ) ) ° 

8.1.10.4 The Idapdelete utility 

The Idapdelete utility is built around the ldap_delete() API. The utility opens a 
connection to an LDAP server, binds to the server, and deletes one or more 
entries. The distinguished names (DNs) of the entries to delete are read from 
standard input or from a file. 

The syntax is: 

Idapdelete [options] [DNs] 
Idapdelete [options] [-f file] 

where: 

dn: one or more items to delete 

file: name of input file containing items to delete 

If neither dn or file is specified then items are read from standard input. The 
options are: 

-h LDAP server host name 
-p LDAP server port number 
-D bind dn 
-w bind password 

-Z use a secure Idap connection (SSL) 
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-K file to use for keys 

-P keyfile password 

-N private key name to use in keyfile 

-m perform SASL bind with the given mechanism 

-R do not chase referrals 

-M Manage referral objects as normal entries 

-O maximum number of referrals to follow to a sequence 

-V LDAP protocol version (2 or 3; default is 3) 

-C character set name to use, as registered with IANA 

-c continuous operation; do not stop processing on error 

-n show what would be done but don't actually do it 

-v verbose mode 

-d level (set debug level in LDAP library 
Examples: -j 

1 . Delete the entries with cn=Karina: 

ldapdelete -h rs6 00030 -D 1 "cn=root* -w swal!7r w cn=Karina, 
Olu=ITSO, o=IBM, o=US" 

2. Delete two entries from a file called IdapDelete: 

"cn^Marifia, ou=IT90, o=IBM, c^JS" 
"OfcCristian, ousXTSO, o=IBM, c=OB* 
\ s J 

ldapdelete -h rs600030 -D swall7r -f IdapDelete 

8.1.11 Configuring the Netscape address book to use LDAP 

The Netscape address book is an LDAP-enabled application, which means 
that it can get information from an LDAP directory. Other products like 
Microsoft Internet Explorer are LDAP enabled too. 

In these examples we show you how to set up the Netscape address book to 
use IBM SecureWay Directory V3.1.1. 

1 . Start the Netscape address book. 
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Figure 407. Netscape address book 
2. Create a new directory. 

Click File -> New Directory and you should see the dialog box shown in 
Figure 408. 




Figure 408. Directory Server Property dialog box 

The fields are: 
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• Description: Title description is optional 

• LDAP Server: Host name of the Directory Server 

• Search Root: Base DN 

• Port Number: By default 389 

• Don't show more than: Maximum number of entries returned 

• Secure: Use SSL 

• Login with name and password: Used to bind with user ID and password 
3. To see all entries, type * in the Show names containing field: 





Personal Add... 



Critian 



roJdanc@ar.imi.com 



fcm 



test Secure... 



HI Netcenter M... 
: M InfoSpace Di. 
H VerwptDrc... 



Figure 409. Search 



£3 Kama karha@ar.fcnL corn fcm 
Marisa Manta@ar.fcra corn fcm 
m WAS fcm 



8.1.12 WebSphere and LDAP 

WebSphere supports authentication mechanisms based on validating 
credentials such as user ID and password, certificates, or tokens. Credentials 
are verified against a user registry supporting such a schema. For example, 
user IDs and password-based authentication can be based on the LDAP user 
registry where authentication is performed using an LDAP bind. A certificate 
validation list may be used in cases where authentication of the user is based 
on the clier.t certificate presented by the user over a mutual SSL connection. 
WebSphere supports a three-party authentication schema, one in which the 
client principal and server principal are authenticated to a mutually trusted 
third-party The third-party in this case is the authentication token server. An 
advantage of a three-party schema is that administration of the user registry 
can be controlled centrally. 
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WebSphere supports the following list of LDAP Directory Servers: 

• Netscape Directory Server Version 3.x and 4.x 

• SecureWay Directory Server Version 2.1 and 3.1.1 

• Lotus Domino Version 4.6 and 5.0 

Additional attributes are available for customizing any of the default filters to 
fit a Directory Server not listed above. 

8.1.13 Configuring WebSphere to use LDAP 

Start the WebSphere Advanced Administrative Console. 

1. Select the Tasks tab, double-click the Security option and you will see a 
window similar to Figure 410: 




Figure 410. Security global settings 



2. Select Specify Global Settings and click the Enable Security field. 

Enable Security: Specifies whether to enable or turn off server security. 
If you deselect this field all the security options specified on resources 
will be unprotected. 
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Security Cache TimeOut: Specifies how many seconds the server 
should cache security information received from the user registry 
(Operating System registry or Directory Server "LDAP"). 

3. Select the Application Defaults tab to specify the following properties: 

Realm Name: Is the security domain where the user will be 
authenticated? If the principal tries to access a resource in a different 
realm, the principal will be prompted to log in to the new realm. It is 
used if Single Sign On (SSO) is used. 

Challenge Type: This option specifies the mechanism used by the 
principal to interchange credentials. If you select Basic, it means that 
the Web browser will prompt the principal for a user ID and password. 




Figure 411. Global settings - Applications Defaults 



4. Click the Authentication Mechanism tab. On this page you specify the 
mechanism used by the security server to authenticate the principal's 
credentials. See Figure 412 on page 431. 
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Lightweight Third Party Authentication (LTPA): Select this option to use 
the LDAP directory server as the registry system. 

Token Expiration: Specifies how many minutes can pass before a client 
using an LTPA token must be authenticated again. We used the default 
value. 




Figure 412. Global settings - Authentication Mechanism 



5. Click the User Registry tab. On this page we specify basic information to 
use the LDAP Directory Server as shown in Figure 413 on page 433. 
These are the attributes that you should change: 

Security Server ID: Type a valid user ID registered in the LDAP 
Directory server used by the Application Server V3 Security server. 
The user ID should have some administrative privileges. 

Security Server Password: Type the password for the security server ID 
user. 
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Directory Type: Select the directory to be used. In our case we used 
SecureWay. 

Host: Type the host name where the LDAP directory is running. In this 
example it is rs600030. 

Port: Specify the LDAP directory port, which by default is 389. We used 
the default value. 

Base Distinguished Name: Use this property to specify the starting 
point for LDAP searches. If you plan to use Domino directory you can 
leave this field blank. In this example we used ou=ITSO,o=IBM,c=US. 
Bind Distinguished Name: Use this property to specify the DN to be 
used for the application server. If you leave it blank the Application 
Server binds using the anonymous ID. In this field we used the LDAP 
administrator cn=root. 

Bind Password: Use this field to specify the password used to bind to 
the LDAP directory. We used the LDAP administrator's password. 

Note: If you get the exception 

org.omg.CORBA.TRANSACTIONJROLLEDBACK when you click the 
Finished button, it means that you probably specified an incorrect user 
ID or password. 
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Figure 413. User Registry properties 



6. Click the Finished button. 

Note: For any change made on the global security settings you must 
restart the node. To do so, click Topology -> WebSphere Admin Domain 
-> Host Name (rs600030). Then right-click the mouse button and select 
stop or restart. You must leave the administrative console. 

You can customize more LDAP attributes such as search filters and certificate 
mapping as shown in Figure 414: 
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Figure 414. Advanced properties 



7. The next step consists of applied security on an application. This means 
performing the following steps: 

a. Configure an enterprise application. 

b. Configure application security. 

c. Configure resource security. 

d. Assign permissions. 

For more information about how to perform these tasks see the 
WebSphere documentation available in the directory 
/usr/WebSphere/AppServer/web/doc/begin_here/index.html 

8.1.14 JNDI 

JNDI defined by Sun Microsystems provides naming and directory functions 
to Java programs. JNDI is an API independent of any specific directory 
service implementation. 

The definition prevents, by design, the appearance of any 
implementation-specific artifacts in the API. The API is designed to cover the 
common case. JNDI was developed as part of Java Enterprise API set which 
also includes Enterprise Java beans (EJB) and Java Database Connectivity 
(JDBC). The EJB specification has a special relationship with JNDI because 
EJB uses this mechanism to find Entity beans or Sessions beans. 
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